說明
請使用 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<鬧鐘|未定義>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
取得所有鬧鐘的陣列。
傳回
-
Promise<鬧鐘[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。