We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

這是一個實驗中的功能
此功能在某些瀏覽器尚在開發中,請參考兼容表格以得到不同瀏覽器用的前輟。

摘要

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

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

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

警示排程

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

注意:若未針對特定 Apps 來設定警示,則只要是正在監聽警示的 Apps,均將接到系統所發送的警示。

忽略時區的警示

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

遵守時區的警示

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

管理警示

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

mozAlarm

這些物件均為非同步 JavaScript 物件,並包含下列屬性:

id
1 組號碼代表警示的 ID
date
Date 物件代表警示的排程時間
respectTimezone
1 組字串指出警示將遵守或忽略 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);
}

處理警示

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

首先,Apps 必須將 alarm 納入本身 manifest 檔案的 message 屬性中,而此 manifest 檔案需包含「已註冊回呼 (Callback) 函式的文件」之網址。一旦發送警示時,就會呼叫該文件中所註冊的回呼函式。

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

其次,Apps 必須以 alarm 訊息綁定回呼函式;可透過 navigator.mozSetMessageHandler 函式完成此步驟。此回呼函式將接收 mozAlarm 物件,其內為警示所附掛的資料。

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

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

navigator.mozHasPendingMessage("alarm");

規格

Specification Status Comment
Web Alarms API Obsolete Initial specification.

瀏覽器相容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support ? 16 (16) moz No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? No support 10.0 (10) moz No support No support No support

另可參閱

文件標籤與貢獻者

此頁面的貢獻者: MashKao
最近更新: MashKao,