From 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:43:23 -0500 Subject: initial commit --- files/zh-tw/webapi/alarm/index.html | 196 ++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 files/zh-tw/webapi/alarm/index.html (limited to 'files/zh-tw/webapi/alarm/index.html') diff --git a/files/zh-tw/webapi/alarm/index.html b/files/zh-tw/webapi/alarm/index.html new file mode 100644 index 0000000000..fc1eddb8d3 --- /dev/null +++ b/files/zh-tw/webapi/alarm/index.html @@ -0,0 +1,196 @@ +--- +title: Alarm API +slug: WebAPI/Alarm +translation_of: Archive/B2G_OS/API/Alarm_API +--- +

{{ SeeCompatTable() }}

+

摘要

+

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 物件的時區資訊。該值可為 ignoreTimezone 或 honorTimezone
+
+ 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");
+
+

規格

+ + + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('Alarm API')}}{{Spec2('Alarm API')}}Initial specification.
+

瀏覽器相容性

+

{{ CompatibilityTable() }}

+
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatUnknown()}}{{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
+
+
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatNo() }}{{CompatGeckoMobile("10")}} {{ property_prefix("moz") }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
+
+

另可參閱

+ -- cgit v1.2.3-54-g00ecf