說明
請使用 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 範例。
設定鬧鐘
下列範例會在安裝擴充功能時在 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 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有鬧鐘。
參數
-
回呼
函式選用
callback
參數如下所示:(wasCleared: boolean) => void
-
wasCleared
boolean
-
傳回
-
Promise<boolean>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
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 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
擷取指定鬧鐘的詳細資料。
傳回
-
Promise<Alarm | undefined>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
取得所有鬧鐘的陣列。
傳回
-
Promise<鬧鐘[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。