mozilla
您的搜尋結果

    Alarm API

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

    摘要

    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 Working Draft Initial specification.

    瀏覽器相容性

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

    另可參閱

    Document Tags and Contributors

    Contributors to this page: MashKao
    最近更新: MashKao,