chrome.alarms

說明

如要安排定期或日後指定時間執行程式碼，請使用 chrome.alarms API。

權限

alarms

如要使用 chrome.alarms API，請在資訊清單中宣告 "alarms" 權限：

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

概念和用法

為確保行為穩定，瞭解 API 的運作方式會很有幫助。

裝置睡眠時間

裝置處於休眠狀態時，鬧鐘會繼續執行。但不會設定鬧鐘 喚醒裝置。裝置喚醒後，所有錯過的鬧鐘都會觸發。 重複的鬧鐘最多只會啟動一次，然後使用 所指定的期間是從裝置喚醒起算，不考量使用者所得的時間 自鬧鐘最初啟動開始後已經過的任何時間。

持續性

在擴充功能更新之前，鬧鐘通常會持續顯示。但是，我們也無法保證 一定會發出警示 也可能在瀏覽器重新啟動時清除。因此，請考慮在儲存空間中設定值 建立新的鬧鐘，接著請確保服務工作處理程序每次啟動時仍存在。例如：

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ periodInMinutes: 1 });
    }
  }
}

checkAlarmState();

範例

下列範例說明如何使用及回應鬧鐘。如要試用這個 API， 從 chrome-extension-samples 安裝 Alarm API 範例 Cloud Storage 也提供目錄同步處理功能

設定鬧鐘

下列範例會在安裝擴充功能時，在 Service Worker 中設定鬧鐘：

service-worker.js：

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

回應鬧鐘

以下範例會根據鬧鐘響起的名稱設定動作工具列圖示。

service-worker.js：

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

類型

Alarm

屬性

  • 名稱

    字串

    這個鬧鐘的名稱。

  • periodInMinutes

    編號 選填

    如果沒有空值，鬧鐘就會是週期性鬧鐘，會在 periodInMinutes 分鐘後再次觸發。

  • scheduledTime

    數字

    設定這個鬧鐘的觸發時間，以毫秒為單位超過 Epoch 紀元時間 (例如 Date.now() + n)。基於效能因素，鬧鐘可能會延遲到超過這個時間。

AlarmCreateInfo

屬性

  • delayInMinutes

    編號 選填

    onAlarm 事件應觸發的時間長度 (以分鐘為單位)。

  • periodInMinutes

    編號 選填

    如果設定這項政策，在 when 或 delayInMinutes 指定的初始事件之後，系統每 periodInMinutes 分鐘就會觸發一次 onAlarm 事件。如果未設定，鬧鐘只會觸發一次。

  • 時段

    編號 選填

    觸發鬧鐘的時間，以毫秒為單位超過 Epoch 紀元時間，例如 Date.now() + n。

方法

clear()

Promise 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

清除指定名稱的鬧鐘。

參數

  • 名稱

    string optional

    要清除的鬧鐘名稱。預設為空字串。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (wasCleared: boolean) => void

    • wasCleared

      布林值

傳回

  • Promise<boolean>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
)

清除所有鬧鐘。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (wasCleared: boolean) => void

    • wasCleared

      布林值

傳回

  • Promise<boolean>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

建立鬧鐘。接近 alarmInfo 指定的時間時，會觸發 onAlarm 事件。如果另一個鬧鐘使用相同的名稱 (或者無指定名稱)，系統將取消該鬧鐘，並由這個鬧鐘取代。

為降低使用者電腦的負載，Chrome 將鬧鐘時間限制為每 30 秒最多一次，但可能會延遲任意數值。也就是說，系統不會遵循將 delayInMinutes 或 periodInMinutes 設為小於 0.5 的情況，且只會發出警告。when可設為在「現在」後不到 30 秒實際上不會觸發鬧鐘觸發至少 30 秒

為協助您對應用程式或擴充功能進行偵錯，在您將應用程式或擴充功能解除封裝後，鬧鐘觸發頻率沒有限制。

參數

  • 名稱

    string optional

    用於辨識這個鬧鐘的名稱。預設為空字串。

  • alarmInfo

    AlarmCreateInfo

    說明鬧鐘的觸發時機。初始時間必須用 when 或 delayInMinutes 指定 (但不能兩者都指定)。如果設定 periodInMinutes，則鬧鐘會在初始事件結束後每 periodInMinutes 分鐘重複一次。如果未為週期性鬧鐘設定 when 或 delayInMinutes，系統會使用 periodInMinutes 做為 delayInMinutes 的預設選項。

  • 回呼

    函式 選用

    Chrome 111 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 111 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

get()

Promise 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

擷取指定鬧鐘的詳細資料。

參數

  • 名稱

    string optional

    要取得的鬧鐘名稱。預設為空字串。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (alarm?: Alarm) => void

傳回

  • Promise&lt;Alarm |未定義>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
)

取得所有鬧鐘的陣列。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (alarms: Alarm[]) => void

傳回

  • Promise<Alarm[]>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

鬧鐘已結束時觸發。適用於活動網頁。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (alarm: Alarm) => void