說明
請使用 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
號碼
這個鬧鐘排定的觸發時間 (以毫秒為單位,例如
Date.now() + n
)。基於效能因素,鬧鐘可能已延遲到這個時間以後的任意金額。
AlarmCreateInfo
屬性
-
delayInMinutes
數字 選填
onAlarm
事件觸發後應觸發的時間長度 (分鐘)。 -
periodInMinutes
數字 選填
如有設定,onAlarm 事件應會在
when
或delayInMinutes
指定的初始事件後每periodInMinutes
分鐘觸發一次。如未設定,鬧鐘只會觸發一次。 -
時段
數字 選填
鬧鐘觸發的時間,以紀元後毫秒為單位 (例如
Date.now() + n
)。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
清除具有指定名稱的鬧鐘。
參數
-
名稱
字串 選用
要清除的鬧鐘名稱。預設為空字串。
-
回呼
函式選用
callback
參數如下所示:(wasCleared: boolean) => void
-
wasCleared
boolean
-
傳回
-
Promise<boolean>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有鬧鐘。
參數
-
回呼
函式選用
callback
參數如下所示:(wasCleared: boolean) => void
-
wasCleared
boolean
-
傳回
-
Promise<boolean>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
建立鬧鐘。在 alarmInfo
指定的時間附近,會觸發 onAlarm
事件。如果已有其他鬧鐘相同的鬧鐘 (或未指定名稱),系統會將該鬧鐘取消並替換成這個鬧鐘。
為減少使用者電腦的負載,Chrome 限制鬧鐘頻率為每 30 秒最多一次,但可能會延遲一些時間。也就是說,系統不會依照將 delayInMinutes
或 periodInMinutes
設為 0.5
的值,並提出警示。您可以將 when
設為在「現在」後 30 秒內 (且沒有事先警告),但實際上不會觸發鬧鐘至少 30 秒。
為協助您對應用程式或擴充功能進行偵錯,在將其解壓縮後,鬧鐘的觸發頻率沒有限制。
參數
-
名稱
字串 選用
用於識別此鬧鐘的選填名稱。預設為空字串。
-
alarmInfo
說明鬧鐘的觸發時機。初始時間必須由
when
或delayInMinutes
指定 (但兩者只能擇一)。如果設定了periodInMinutes
,鬧鐘會在初始事件後每periodInMinutes
分鐘重複一次。如未將when
或delayInMinutes
設為週期性鬧鐘,periodInMinutes
將設為delayInMinutes
的預設鬧鐘。 -
回呼
函式選用
Chrome 111 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 111 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
擷取指定鬧鐘的詳細資料。
傳回
-
Promise<Alarm | undefined>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getAll()
chrome.alarms.getAll(
callback?: function,
)
取得所有鬧鐘的陣列。
傳回
-
Promise<鬧鐘[]>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。