Alarm API

非标准
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

Alarm API允许应用程序设定将来运行的操作。例如,一些应用程序(如闹钟、日历或自动更新)可能需要使用Alarm API在指定的时间点触发特定的设备行为。

Alarm API本身只允许调度警报。Alarm 通过系统消息API发送到应用程序,因此希望对警报作出响应的应用程序必须将自己注册到Alarm 消息中。

Alarm 使用 Navigator.mozAlarms对象设置,该对象是MozAlarmsManager接口的一个实例。

注: 这里的‘“闹钟 ”(Alarm API)并不同于闹铃App。Alarm API 唤醒应用程序, 闹钟叫醒人. 闹钟 使用 Alarm API 设置通知,用来在正确的时间叫醒人。(译者注:疑问脸)

设置闹铃

使用闹铃时要做的第一件事是设置闹铃。根据时区的不同,有两种警报。在这两种情况下,它都是使用MozAlarmsManager.add()方法完成的。

Note: 如果警报不是针对特定应用程序的,系统会将所有警报发送给所有监听警报的应用程序。

Note: 您需要使用相同的URL来设置和接收警报。例如,如果在foo.html或index.html?foo=bar上调用navigator.mozAlarms.add(),但在清单消息字段中有{ "alarm": "/index.html" },您将永远不会收到警报。

Alarms 忽略时区

这类警报是根据设备的本地时间发出的。如果设备用户更改了时区,将根据新的时区发出警报。例如,如果用户在巴黎,设置了一个应该在CET(中欧时间)下午12点发出的警报,而该用户前往旧金山,那么该警报将在PDT(太平洋夏令时)下午12点发出。

// 设定闹钟的日期
var myDate  = new Date("May 15, 2012 16:20:00");

// 传递给警报的任意数据
var data    = {
  foo: "bar"
}

// 使警报忽略"ignoreTimezone"
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);
};

时区警报

这些类型的警报是根据定义警报计划时间的时区中的时间发出的。如果由于某种原因,设备的用户更改了时区,将根据原始时区发出警报。例如,如果用户在巴黎,并设置一个闹钟,该闹钟应该在CET(中欧时间)下午12点发出,如果该用户前往旧金山,该闹钟将在太平洋夏令时凌晨3点发出。

// 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);
};

管理警报

 

设定警报后,仍然可以管理它。

方法将返回应用程序当前调度的警报的完整列表。这个列表是一个mozAlarm对象数组。

 

 

mozAlarm

 

匿名JavaScript对象,具有以下属性:

 

id

表示警报id

date

表示警报的预定时间的日期对象

respectTimezone

一个字符串,指示警报是否必须尊重或忽略date对象的时区信息。它的值可以是ignoreTimezonehonorTimezone

data

一个JavaScript对象,包含警报存储的所有数据

 

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);
};

MozAlarmsManager.remove 用于取消现有警报的调度。

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);
}

处理警报

 

当系统发出警报时,任何应用程序都可以作出反应。为了能够处理任何警报,应用程序必须将自己注册为警报处理程序。这是通过系统消息API分两个步骤完成的:

首先,应用程序必须将alarm包含到其应用程序清单的messages属性中,并提供到文档的URL,文档注册在发出警报时使用的回调函数。

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

其次,应用程序必须将回调函数与警报消息绑定。这是使用Navigator.mozSetMessageHandler()方法完成的。这个回调函数将接收一个mozAlarm对象,其中包含附加到警报的数据。

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

如果应用程序想知道系统级别上是否存在挂起的警报,可以使用下面的方法。

navigator.mozHasPendingMessage("alarm"); 

权限 Alarm API

请注意,虽然警报API没有特权或认证,但您仍然应该在清单中包含权限消息条目。当包含在可安装的打开的Web应用程序中的manifest.webapp文件。

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

规范

Specification Status Comment
Web Alarms API Obsolete Initial specification.

浏览器兼容性

Supported in Firefox OS 1.0.1.

另请参阅