說明
使用 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
數字
這個鬧鐘預定觸發的時間，以自 Epoch 以來的毫秒數表示 (例如
Date.now() + n)。基於效能考量，鬧鐘可能會延遲任意時間。
AlarmCreateInfo
屬性
-
delayInMinutes
號碼 選填
onAlarm事件應在幾分鐘後觸發。 -
periodInMinutes
號碼 選填
如果已設定，onAlarm 事件應在
when或delayInMinutes指定的初始事件後，每隔periodInMinutes分鐘觸發一次。如未設定，鬧鐘只會響一次。 -
when
號碼 選填
鬧鐘觸發時間，以 Epoch 時間後的毫秒數表示 (例如
Date.now() + n)。
方法
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
清除指定名稱的鬧鐘。
參數
-
名稱
字串 選填
要清除的警報名稱。預設為空字串。
傳回
-
Promise<boolean>
Chrome 91 以上版本
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
清除所有鬧鐘。
傳回
-
Promise<boolean>
Chrome 91 以上版本
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
設定鬧鐘。在 alarmInfo 指定的時間附近，系統會觸發 onAlarm 事件。如果已有同名鬧鐘 (或未指定名稱)，系統會取消該鬧鐘，並改為設定這個鬧鐘。
為減少使用者電腦的負載，Chrome 會限制每 30 秒最多觸發一次鬧鐘，但可能會任意延遲鬧鐘。也就是說，如果將 delayInMinutes 或 periodInMinutes 設為小於 0.5 的值，系統不會採用，並會發出警告。when 可設為「現在」之後不到 30 秒，但鬧鐘至少要 30 秒後才會響起。
為協助您偵錯應用程式或擴充功能，當您載入未封裝的應用程式或擴充功能時，鬧鐘的觸發頻率不受限制。
參數
-
名稱
字串 選填
(選用) 用於識別這個鬧鐘的名稱。預設為空字串。
-
alarmInfo
說明鬧鐘的觸發時間。初始時間必須由
when或delayInMinutes指定 (但不能同時指定)。如果設定periodInMinutes，鬧鐘會在初始事件發生後每隔periodInMinutes分鐘重複響鈴。如果未針對重複鬧鐘設定when或delayInMinutes，系統會預設使用periodInMinutes做為delayInMinutes。
傳回
-
Promise<void>
Chrome 111 以上版本
參數
-
名稱
字串 選填
要取得的鬧鐘名稱。預設為空字串。
傳回
-
Promise<Alarm | undefined>
Chrome 91 以上版本
傳回
-
Promise<Alarm[]>
Chrome 91 以上版本