chrome.alarms

說明

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

權限

alarms

資訊清單

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

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

範例

下列範例說明如何使用及回應鬧鐘。如要試用這個 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