修改 451065 of Alarm API

  • 版本網址代稱: WebAPI/Alarm
  • 版本標題: Alarm API
  • 版本 ID: 451065
  • 建立日期:
  • 建立者: MashKao
  • 是目前線上的版本?
  • 回應

版本內容

{{ SeeCompatTable() }}

摘要

Alarm API 可存取裝置的警示設定功能。而警示設定功能可排定通知的時間,或在特定時間啟動某個 App。如鬧鐘、行事曆、自動更新等的 App,就可能需要透過 Alarm API,在特定時點觸發裝置的特定動作。

而 Alarm API 本身僅可排定警示。透過 System Message API 即可將警示發送到 App,因此若 App 要對警示做出反應,就必須將該 App 註冊至 alarm 訊息。

另外,使用 MozAlarmsManager 介面的 window.navigator.mozAlarms 物件,即可設定警示。

警示排程

使用警示功能的第一件事,就是排程警示。若依照時區來分,共可分成 2 種警示,而均可透過 MozAlarmsManager.add 函式完成排程。

注意:若設定警示時並未針對特定 App,則系統將發送警示至所有「正監聽警示」的 App。

忽略時區的警示

系統將根據裝置的本端時間,發送此類警示。若裝置變更了時區設定,則系統一將根據新的時區而發送警示。舉例來說,如果使用者位在巴黎,設定了 12:00 PM CET (Central European Time) 發出警示,結果出差到舊金山時,那同樣會在 12:00 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 schedule");
};

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

遵守時區的警示

系統將根據排程當下的時區,發送此類警示。若裝置因為某個理由變更了時區,系統同樣是根據原始的排程時區而發出警示。舉例來說,如果使用者位在巴黎,設定了 12:00 PM CET (Central European Time) 發送警示,結果出差到舊金山時,系統將於 3:00 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 schedule");
};

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

管理警示

在警示排程完畢之後,仍可能後續管理警示。

針對目前 App 已排定的警示,MozAlarmsManager.getAll 函式將回傳完整的警示清單。這份清單則為物件的陣列

{{page("/en-US/docs/Web/API/MozAlarmsManager.getAll","mozAlarm")}}

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: " + e.target.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.id;
}

// ...

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

處理警示

在系統發送警示之後,任何 App 均可做出回應。為了要能處理警示,App 必須將本身註冊為警示處理器 (Alarm handler)。透過 System Messaging API 的 2 個步驟即可完成註冊:

首先,App 必須將 alarm 納入本身 manifest 檔案的 message 屬性中,而此 manifest 又需包含回呼 (Callback) 文件的 URL。一旦發送警示時,就會回呼到之前 manifest 中所指定的 URL。

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

再來,App 必須以 alarm 訊息綁定回呼函式;可透過 navigator.mozSetMessageHandler 函式完成此步驟。而此「附加於警示且作為警示的第一筆參數」的資料,即為回呼函式所接收的資料。

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

如果 App 想確認是否有警示延宕在系統端尚未發出,則可使用navigator.mozHasPendingMessage 函式並搭配 alarm 值。

navigator.mozHasPendingMessage("alarm"); 

規格

Specification Status Comment
{{SpecName('Alarm API')}} {{Spec2('Alarm API')}} Initial specification.

瀏覽器相容性

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatUnknown()}} {{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatNo() }} {{CompatGeckoMobile("10")}} {{ property_prefix("moz") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

另可參閱

  • {{domxref("window.navigator.mozAlarms","navigator.mozAlarms")}}
  • {{domxref("MozAlarmsManager")}}
  • {{domxref("window.navigator.mozSetMessageHandler")}}

版本來源

<p>{{ SeeCompatTable() }}</p>
<h2 id=".E6.91.98.E8.A6.81">摘要</h2>
<p><span class="external">Alarm API</span> 可存取裝置的警示設定功能。而警示設定功能可排定通知的時間,或在特定時間啟動某個 App。如鬧鐘、行事曆、自動更新等的 App,就可能需要透過 Alarm API,在特定時點觸發裝置的特定動作。</p>
<p>而 Alarm API 本身僅可排定警示。透過 System Message API 即可將警示發送到 App,因此若 App 要對警示做出反應,就必須將該 App 註冊至 <code>alarm</code> 訊息。</p>
<p>另外,使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MozAlarmsManager" title="/en-US/docs/Web/API/MozAlarmsManager"><code>MozAlarmsManager</code></a> 介面的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozAlarms" title="/en-US/docs/Web/API/window.navigator.mozAlarms"><code>window.navigator.mozAlarms</code></a> 物件,即可設定警示。</p>
<h2 id="example" name="example">警示排程</h2>
<p>使用警示功能的第一件事,就是排程警示。若依照時區來分,共可分成 2 種警示,而均可透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MozAlarmsManager.add" title="/en-US/docs/Web/API/MozAlarmsManager.add"><code>MozAlarmsManager.add</code></a> 函式完成排程。</p>
<div class="note">
  <p><strong>注意:</strong>若設定警示時並未針對特定 App,則系統將發送警示至所有「正監聽警示」的 App。</p>
</div>
<h3 id=".E5.BF.BD.E7.95.A5.E6.99.82.E5.8D.80.E7.9A.84.E8.AD.A6.E7.A4.BA">忽略時區的警示</h3>
<p>系統將根據裝置的本端時間,發送此類警示。若裝置變更了時區設定,則系統一將根據新的時區而發送警示。舉例來說,如果使用者位在巴黎,設定了 12:00 PM CET (<em>Central European Time</em>) 發出警示,結果出差到舊金山時,那同樣會在 12:00 PM PDT (<em>Pacific Daylight Time</em>) 發送警示。</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 "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 schedule");
};

request.onerror = function () { 
  console.log("An error occurred: " + e.target.error.name);
};
</pre>
<h3 id=".E9.81.B5.E5.AE.88.E6.99.82.E5.8D.80.E7.9A.84.E8.AD.A6.E7.A4.BA">遵守時區的警示</h3>
<p>系統將根據排程當下的時區,發送此類警示。若裝置因為某個理由變更了時區,系統同樣是根據原始的排程時區而發出警示。舉例來說,如果使用者位在巴黎,設定了 12:00 PM CET (<em>Central European Time</em>) 發送警示,結果出差到舊金山時,系統將於 3:00 AM PDT (<em>Pacific Daylight Time</em>) 發送警示。</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 schedule");
};

request.onerror = function () { 
  console.log("An error occurred: " + e.target.error.name);
};
</pre>
<h2 id=".E7.AE.A1.E7.90.86.E8.AD.A6.E7.A4.BA">管理警示</h2>
<p>在警示排程完畢之後,仍可能後續管理警示。</p>
<p>針對目前 App 已排定的警示,<a href="https://developer.mozilla.org/en-US/docs/Web/API/MozAlarmsManager.getAll" title="/en-US/docs/Web/API/MozAlarmsManager.getAll"><code>MozAlarmsManager.getAll</code></a> 函式將回傳完整的警示清單。這份清單則為物件的<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">陣列</a>。</p>
<p>{{page("/en-US/docs/Web/API/MozAlarmsManager.getAll","mozAlarm")}}</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: " + e.target.error.name);
};
</pre>
<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/MozAlarmsManager.remove" title="/en-US/docs/Web/API/MozAlarmsManager.remove"><code>MozAlarmsManager.remove</code></a> 函式則可解除已排程的警示。</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.id;
}

// ...

// Later on, removing the alarm if it exists
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}
</pre>
<h2 id=".E8.99.95.E7.90.86.E8.AD.A6.E7.A4.BA">處理警示</h2>
<p>在系統發送警示之後,任何 App 均可做出回應。為了要能處理警示,App 必須將本身註冊為警示處理器 (Alarm handler)。透過 System Messaging API 的 2 個步驟即可完成註冊:</p>
<p>首先,App 必須將 <code>alarm</code> 納入<a href="https://developer.mozilla.org/en-US/docs/Apps/Manifest#messages" title="/en-US/docs/Apps/Manifest#messages">本身 manifest 檔案的 message 屬性</a>中,而此 manifest 又需包含回呼 (Callback) 文件的 URL。一旦發送警示時,就會回呼到之前 manifest 中所指定的 URL。</p>
<pre class="brush: js">
"messages": [
  { "alarm": "/index.html" }
]</pre>
<p>再來,App 必須以 <code>alarm</code> 訊息綁定回呼函式;可透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozSetMessageHandler" title="/en-US/docs/Web/API/window.navigator.mozSetMessageHandler"><code>navigator.mozSetMessageHandler</code></a> 函式完成此步驟。而此「附加於警示且作為警示的第一筆參數」的資料,即為回呼函式所接收的資料。</p>
<pre class="brush: js">
navigator.mozSetMessageHandler("alarm", function (data) { 
  alert("alarm fired: " + JSON.stringify(data)); 
});
</pre>
<p>如果 App 想確認是否有警示延宕在系統端尚未發出,則可使用<a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozHasPendingMessage" title="/en-US/docs/Web/API/window.navigator.mozHasPendingMessage"><code>navigator.mozHasPendingMessage</code></a> 函式並搭配 <code>alarm</code> 值。</p>
<pre class="brush: js">
navigator.mozHasPendingMessage("alarm"); 
</pre>
<h2 id=".E8.A6.8F.E6.A0.BC">規格</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=".E7.80.8F.E8.A6.BD.E5.99.A8.E7.9B.B8.E5.AE.B9.E6.80.A7">瀏覽器相容性</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown()}}</td>
        <td>{{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Chrome for Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{CompatGeckoMobile("10")}} {{ property_prefix("moz") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id=".E5.8F.A6.E5.8F.AF.E5.8F.83.E9.96.B1">另可參閱</h2>
<ul>
  <li>{{domxref("window.navigator.mozAlarms","navigator.mozAlarms")}}</li>
  <li>{{domxref("MozAlarmsManager")}}</li>
  <li>{{domxref("window.navigator.mozSetMessageHandler")}}</li>
</ul>
還原至此版本