path: root/files/zh-cn/archive/b2g_os/api/alarm_api/index.html

---
title: Alarm API
slug: Archive/B2G_OS/API/Alarm_API
tags:
  - API
  - Firefox OS
  - 警报
translation_of: Archive/B2G_OS/API/Alarm_API
---
<p>{{DefaultAPISidebar("Alarm API")}}{{Non-standard_Header}}</p>

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

<p class="summary"><strong>Alarm API</strong>本身只允许调度警报。<strong>Alarm </strong>通过系统消息API发送到应用程序，因此希望对警报作出响应的应用程序必须将自己注册到<strong>Alarm </strong>消息中。</p>

<p><strong>Alarm </strong>使用 {{DOMxRef("Navigator.mozAlarms")}}对象设置，该对象是{{DOMxRef("MozAlarmsManager")}}接口的一个实例。</p>

<div class="blockIndicator note">
<p><em><strong>注:</strong></em> 这里的‘“闹钟 ”（<strong>Alarm API</strong>）并不同于闹铃App。<strong>Alarm API </strong>唤醒应用程序, 闹钟叫醒人. 闹钟 <a href="https://github.com/mozilla-b2g/gaia/blob/master/apps/clock/js/alarm.js">使用 Alarm API</a> 设置通知，用来在正确的时间叫醒人。（译者注：疑问脸）</p>
</div>

<h2 id="example" name="example">设置闹铃</h2>

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

<div class="blockIndicator note">
<p><strong>Note:</strong> 如果警报不是针对特定应用程序的，系统会将所有警报发送给所有监听警报的应用程序。</p>
</div>

<div class="blockIndicator note">
<p><strong>Note</strong>: 您需要使用相同的<strong>URL</strong>来设置和接收警报。例如，如果在foo.html或index.html?foo=bar上调用<code>navigator.mozAlarms.add()</code>，但在<a href="/en-US/Apps/Build/Manifest#messages">清单消息字段</a>中有<code style="white-space: nowrap;">{ "alarm": "/index.html" }</code>，您将永远不会收到警报。</p>
</div>

<h3 id="Alarms_忽略时区">Alarms 忽略时区</h3>

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

<pre class="brush: js;">// 设定闹钟的日期
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);
};</pre>

<h3 id="时区警报">时区警报</h3>

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

<pre class="brush: js;">// 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);
};</pre>

<h2 id="管理警报">管理警报</h2>

<p> </p>

<p>设定警报后，仍然可以管理它。</p>

<p>方法将返回应用程序当前调度的警报的完整列表。这个列表是一个{{anch("mozAlarm")}}对象数组。</p>

<p> </p>

<p> </p>

<h3 id="mozAlarm">mozAlarm</h3>

<p> </p>

<p>匿名JavaScript对象，具有以下属性:</p>

<p> </p>

<p><code>id</code></p>

<p>表示警报id</p>

<p><code>date</code></p>

<p>表示警报的预定时间的日期对象</p>

<p><code>respectTimezone</code></p>

<p>一个字符串，指示警报是否必须尊重或忽略date对象的时区信息。它的值可以是<code>ignoreTimezone</code>或<code>honorTimezone</code></p>

<p><code>data</code></p>

<p>一个JavaScript对象，包含警报存储的所有数据</p>

<p> </p>

<pre class="brush: js;">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);
};</pre>

<p>{{DOMxRef("MozAlarmsManager.remove")}} 用于取消现有警报的调度。</p>

<pre class="brush: js;">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);
}</pre>

<h2 id="处理警报">处理警报</h2>

<p> </p>

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

<p>首先，应用程序必须将alarm包含到其应用程序清单的<a href="/en-US/docs/Apps/Manifest#messages">messages</a>属性中，并提供到文档的URL，文档注册在发出警报时使用的回调函数。</p>

<pre class="brush: js;">"messages": [
  { "alarm": "/index.html" }
]</pre>

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

<pre class="brush: js;">navigator.mozSetMessageHandler("alarm", function (mozAlarm) {
  alert("alarm fired: " + JSON.stringify(mozAlarm.data));
});</pre>

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

<pre class="brush: js;">navigator.mozHasPendingMessage("alarm"); </pre>

<h2 id="权限_Alarm_API">权限 Alarm API</h2>

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

<pre class="brush: json;">{
  "permissions": {
    "alarms": {
      "description": "Required to schedule alarms"
    }
  },
  "messages": [
    { "alarm": "/index.html" }
  ]
}</pre>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName("Alarm API")}}</td>
   <td>{{Spec2("Alarm API")}}</td>
   <td>Initial specification.</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>Supported in Firefox OS 1.0.1.</p>

<h2 id="另请参阅">另请参阅</h2>

<ul>
 <li><a href="/en-US/Apps/Build/User_notifications/Using_Alarms_to_notify_users">使用警报通知用户</a></li>
 <li>{{DOMxRef("Navigator.mozAlarms")}}</li>
 <li>{{DOMxRef("MozAlarmsManager")}}</li>
 <li>{{DOMxRef("Navigator.mozSetMessageHandler")}}</li>
</ul>