MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Alarm API

この翻訳は不完全です。英語から この記事を翻訳 してください。

これは実験段階の機能です。
この機能は複数のブラウザで開発中の状態にあります。各ブラウザで用いるために、適切なベンダー接頭辞が必要な場合があります。互換性テーブルをチェックしてください。また、実験段階の機能の構文と挙動は、仕様変更に伴い各ブラウザの将来のバージョンで変更になる可能性があることに注意してください。

要約

Alarm APIが、アプリケーションが予定された行動を実行することを可能にするのは未来のことです。例として、アラームクロックのようなもの、カレンダーなど。また、自動更新は指定された時刻にデバイスを動作させるために、アラームAPIを利用しなければならない場合があります。

それ単体では、Alarm APIは単にアラームを予定することができます。アラームはSystem Message APIを介してアプリケーションに派遣されているので、 アラームに反応するようにしたいアプリケーションは、アラームメッセージに自分自身を登録する必要があります。

Alarms are set using the window.navigator.mozAlarms object which is an instance of the MozAlarmsManager interface.

Note: The term alarm in the Alarms API is not the same as an alarm used by the Clock app. The Alarms API wakes up applications, the Clock wakes up humans. The Clock uses the Alarm API to be notified when the time is right to wake up humans.

Schedule alarms

The first things to do when using alarm is to schedule alarms. There are two kind of alarms based on the respect of the time zone. In both case it's done using the MozAlarmsManager.add method.

Note: If an alarm is not targeted at a specific application, the system will dispatch all the alarms to all the applications listening for alarms.

Note: You need to use the same URL for setting and receiving an alarm. For example, If you invoke navigator.mozAlarms.add() on foo.html or index.html?foo=bar, but have { "alarm": "/index.html" } in your manifest messages field, you'll never receive the alarm.

Alarms ignoring time zones

Those kind of alarms is dispatched based on the local time of the device. If the user of the device changes its time zone, the alarm will be dispatched based on the new time zone. For example, if a user is in Paris and sets an alarm that should be dispatched at 12 PM CET (Central European Time) and that user travels to San Francisco, the alarm will be dispatched at 12 PM PDT (Pacific Daylight Time).

// This the date to schedule the alarm
var myDate  = new Date("May 15, 2012 16:20:00");

// This is arbitrary data pass to the alarm
var data    = {
  foo: "bar"
}

// The "ignoreTimezone" string is what make the alarm ignoring it
var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);

request.onsuccess = function () {
  console.log("The alarm has been scheduled");
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};

Alarms honoring time zones

Those kind of alarms are dispatched based on the time in the time zone that defines when the alarm has been scheduled. If for some reason, the user of the device changes its time zone the alarm will be dispatched based on the original time zone. For example, if a user is in Paris and set an alarm that should be dispatched at 12pm CET (Central European Time) and if that user travel to San Francisco, the alarm will be dispatched at 3 AM PDT (Pacific Daylight Time).

// This the date to schedule the alarm
var myDate  = new Date("May 15, 2012 16:20:00");

// This is arbitrary data pass to the alarm
var data    = {
  foo: "bar"
}

// The "honorTimezone" string is what make the alarm honoring it
var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);

request.onsuccess = function () {
  console.log("The alarm has been scheduled");
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};

Managing alarms

Once an alarm is scheduled, it's still possible to manage it.

The MozAlarmsManager.getAll method will return the complete list of alarms currently scheduled by the application. This list is an Array of mozAlarm objects.

mozAlarm

Those objects are anonymous JavaScript objects with the following properties:

id
A number representing the id of the alarm
date
A Date object representing the scheduled time for the alarm
respectTimezone
A string indicating if the alarm must respect or ignore the timezone information of the date object. Its value can be ignoreTimezone or honorTimezone
data
A JavaScript object contaning any data that were stored with the alarm

var request = navigator.mozAlarms.getAll();

request.onsuccess = function () {
  this.result.forEach(function (alarm) {
    console.log('Id: ' + alarm.id);
    console.log('date: ' + alarm.date);
    console.log('respectTimezone: ' + alarm.respectTimezone);
    console.log('data: ' + JSON.stringify(alarm.data));
  });
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};

The MozAlarmsManager.remove method is used to unschedule an existing alarm.

var alarmId;

// Set an alarm and store it's id
var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");

request.onsuccess = function () {
  alarmId = this.result;
}

// ...

// Later on, removing the alarm if it exists
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}

Handling alarms

Any application can react when an alarm is dispatched by the system. In order to be able to handle any alarms, an application must register itself as an alarm handler. This is done through the System Messaging API in two steps:

First, the applications must include alarm to the messages property of its application manifest with the URL to the document which registers the callback function to be used when an alarm is dispatched.

"messages": [
  { "alarm": "/index.html" }
]

Second, the application must bind a callback function with the alarm message. This is done using the navigator.mozSetMessageHandler method. This callback function will receive a mozAlarm object containing the data attached to the alarm.

navigator.mozSetMessageHandler("alarm", function (mozAlarm) { 
  alert("alarm fired: " + JSON.stringify(mozAlarm.data)); 
});

If an application wants to know if there is a pending alarm at the system level, it's possible to use the navigator.mozHasPendingMessage method with the value alarm.

navigator.mozHasPendingMessage("alarm"); 

Permissions for the Alarm API

Please note that while the Alarm API is not privileged or certified, you should still include permissions and messages entries in your manifest.webapp file when including it in an installable open Web app.

"permissions": {
    "alarms": {
      "description": "Required to schedule alarms"
    }
  },
  "messages": [
    { "alarm": "/index.html" }
  ]

Specifications

Specification Status Comment
Web Alarms API 草案 Initial specification.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support ? 16 (16) moz 未サポート 未サポート 未サポート
Feature Android Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support ? 未サポート 10.0 (10) moz 1.0.1 未サポート 未サポート 未サポート

See also

ドキュメントのタグと貢献者

 このページの貢献者: xatu0202
 最終更新者: xatu0202,