chrome.alarms

說明

使用 chrome.alarms API 安排程式碼定期執行，或在未來指定時間執行。

權限

alarms

資訊清單

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

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

範例

下列範例說明如何使用及回應鬧鐘。如要試用這個 API，請從 chrome-extension-samples 存放區安裝 Alarm API 範例。

設定鬧鐘

以下範例會在安裝擴充功能時，在 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

    號碼 選填

    如果已設定，onAlarm 事件應在 when 或 delayInMinutes 指定的初始事件後，每隔 periodInMinutes 分鐘觸發一次。如未設定，鬧鐘只會響一次。

  • when

    號碼 選填

    鬧鐘觸發時間，以 Epoch 時間後的毫秒數表示 (例如 Date.now() + n)。

方法

clear()

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

清除指定名稱的鬧鐘。

參數

  • 名稱

    字串 選填

    要清除的警報名稱。預設為空字串。

  • callback

    函式 選用

    callback 參數如下： 

    (wasCleared: boolean) => void

    • wasCleared

      布林值

傳回

  • Promise<boolean>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

clearAll()

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

清除所有鬧鐘。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (wasCleared: boolean) => void

    • wasCleared

      布林值

傳回

  • Promise<boolean>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

create()

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

設定鬧鐘。在 alarmInfo 指定的時間附近，系統會觸發 onAlarm 事件。如果已有同名鬧鐘 (或未指定名稱)，系統會取消該鬧鐘，並改為設定這個鬧鐘。

為減少使用者電腦的負載，Chrome 會限制每 30 秒最多觸發一次鬧鐘，但可能會任意延遲鬧鐘。也就是說，如果將 delayInMinutes 或 periodInMinutes 設為小於 0.5 的值，系統不會採用，並會發出警告。when 可設為「現在」之後不到 30 秒，但鬧鐘至少要 30 秒後才會響起。

為協助您偵錯應用程式或擴充功能，當您載入未封裝的應用程式或擴充功能時，鬧鐘的觸發頻率不受限制。

參數

  • 名稱

    字串 選填

    (選用) 用於識別這個鬧鐘的名稱。預設為空字串。

  • alarmInfo

    AlarmCreateInfo

    說明鬧鐘的觸發時間。初始時間必須由 when 或 delayInMinutes 指定 (但不能同時指定)。如果設定 periodInMinutes，鬧鐘會在初始事件發生後每隔 periodInMinutes 分鐘重複響鈴。如果未針對重複鬧鐘設定 when 或 delayInMinutes，系統會預設使用 periodInMinutes 做為 delayInMinutes。

  • callback

    函式 選用

    Chrome 111 以上版本

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

get()

Promise 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

擷取指定警報的詳細資料。

參數

  • 名稱

    字串 選填

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

  • callback

    函式 選用

    callback 參數如下： 

    (alarm?: Alarm) => void

傳回

  • Promise<Alarm | undefined>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

取得所有鬧鐘的陣列。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (alarms: Alarm[]) => void

傳回

  • Promise<Alarm[]>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onAlarm

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

鬧鐘時間到時觸發。適用於活動頁面。

參數

  • callback

    函式

    callback 參數如下： 

    (alarm: Alarm) => void