說明
使用 chrome.alarms API 排定程式碼定期執行，或在未來指定時間執行。
權限
alarms如要使用 browser.alarms API，請在資訊清單中宣告 "alarms" 權限：
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
概念和用途
為確保行為可靠，瞭解 API 的行為方式會很有幫助。
裝置休眠
裝置處於休眠狀態時，鬧鐘仍會繼續運作。不過，鬧鐘不會喚醒裝置。裝置喚醒後，系統會觸發所有錯過的鬧鐘。重複鬧鐘最多會觸發一次，然後從裝置喚醒時開始，使用指定的時間週期重新排程，不考慮鬧鐘原本設定執行後經過的時間。
保留設定
建立鬧鐘時，您可以使用 persistAcrossSessions 旗標控制鬧鐘的持續性。可設為 true (保留至擴充功能更新) 或 false (擴充功能重新載入、瀏覽器重新啟動，或擴充功能更新時清除)。
其他瀏覽器和舊版 Chrome
其他瀏覽器 (問題) 或 Chrome 150 之前的 Chrome 版本不支援這項屬性，行為可能無法預測。因此，最好在每次 Service Worker 啟動時，確認重要鬧鐘是否存在。例如：
async function checkAlarmState() {
const alarm = await browser.alarms.get("my-alarm");
if (!alarm) {
await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
如果鬧鐘是根據使用者動作動態建立，建議您將鬧鐘建立資訊儲存在其他位置，以便在需要時重新建立。
範例
以下範例說明如何使用及回應鬧鐘。如要試用這個 API，請從 chrome-extension-samples 存放區安裝 Alarm API 範例。
設定鬧鐘
以下範例會在安裝新版擴充功能時，在 Service Worker 中設定鬧鐘：
service-worker.js：
browser.runtime.onInstalled.addListener(async ({ reason }) => {
// Create an alarm so we have something to look at in the demo
await browser.alarms.create('demo-default-alarm', {
delayInMinutes: 1,
periodInMinutes: 1,
persistAcrossSessions: true
});
});
回應警報
以下範例會根據響起的鬧鐘名稱，設定動作工具列圖示。
service-worker.js：
browser.alarms.onAlarm.addListener((alarm) => {
browser.action.setIcon({
path: getIconPath(alarm.name),
});
});
類型
Alarm
屬性
-
名稱
字串
這個鬧鐘的名稱。
-
periodInMinutes
數字 選填
如果不是空值，鬧鐘會重複，並在
periodInMinutes分鐘後再次響起。 -
persistAcrossSessions
布林值
Chrome 150+鬧鐘是否應在工作階段 (瀏覽器重新啟動) 之間保留。
-
scheduledTime
數字
這個鬧鐘預定響起的時間，以紀元時間後的毫秒數表示 (例如
Date.now() + n)。基於效能考量，鬧鐘可能會延遲任意時間。
AlarmCreateInfo
屬性
-
delayInMinutes
數字 選填
onAlarm事件應在幾分鐘後觸發。 -
名稱
字串 選填
Chrome 152 以上版本這個鬧鐘的名稱。
-
periodInMinutes
數字 選填
如果設定，onAlarm 事件應在
when或delayInMinutes指定的初始事件後，每periodInMinutes分鐘觸發一次。如未設定，鬧鐘只會響一次。 -
persistAcrossSessions
布林值 選填
Chrome 150+鬧鐘是否應在工作階段 (瀏覽器重新啟動) 之間保留。在 Chrome 中，這個欄位預設為 true，以符合過往行為，但建議您明確設定這個欄位，盡可能提高跨瀏覽器相容性。
-
時段
數字 選填
鬧鐘響起的時間，以 Epoch 時間計算的毫秒為單位 (例如
Date.now() + n)。
方法
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
清除指定名稱的鬧鐘。
參數
-
名稱
字串 選填
要清除的警報名稱。(預設為空白字串)。
傳回
-
Promise<boolean>
Chrome 91 以上版本
clearAll()
chrome.alarms.clearAll(): Promise<boolean | undefined>
清除所有鬧鐘。
傳回
-
Promise<boolean | undefined>
Chrome 91 以上版本
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
建立鬧鐘。在 alarmInfo 指定的時間前後，系統會觸發 onAlarm 事件。如果已有同名鬧鐘 (或未指定名稱)，系統會取消該鬧鐘，並以這個鬧鐘取代。
為減輕使用者電腦的負載，Chrome 限制鬧鐘最多每秒響一次，但可能會延遲任意時間。也就是說，如果將 delayInMinutes 或 periodInMinutes 設為小於 1 秒，系統不會接受，並會顯示警告。when 可設為「現在」之後不到 1 秒，系統不會顯示警告，但鬧鐘至少要過 1 秒才會響起。
參數
-
名稱
字串 選填
可選填名稱，用於識別這個鬧鐘。(預設為空白字串)。
-
alarmInfo
說明鬧鐘應響起的時間。初始時間必須由
when或delayInMinutes指定 (但不能同時指定)。如果設定periodInMinutes，鬧鐘會在初始事件後每periodInMinutes分鐘重複一次。如果重複鬧鐘未設定when或delayInMinutes，系統會使用periodInMinutes做為delayInMinutes的預設值。
傳回
-
承諾<void>
Chrome 111 以上版本鬧鐘建立完成後，Promise 就會解析。
參數
-
名稱
字串 選填
要取得的鬧鐘名稱。(預設為空白字串)。
傳回
-
Promise<Alarm | undefined>
Chrome 91 以上版本
傳回
-
Promise<Alarm[]>
Chrome 91 以上版本