說明
使用 chrome.alarms API 排定程式碼，以便定期執行或在未來的特定時間執行。
權限
alarms如要使用 chrome.alarms API，請在manifest中宣告 "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 存放區安裝鬧鐘 API 範例。
設定鬧鐘
以下範例會在安裝擴充功能時，在服務工作站中設定鬧鐘：
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
號碼 選填
如果已設定，則在
when或delayInMinutes指定的初始事件發生後，onAlarm 事件應每隔periodInMinutes分鐘觸發一次。如未設定，鬧鐘只會觸發一次。 -
時段
號碼 選填
鬧鐘應觸發的時間，以 Epoch 紀元時間 (例如
Date.now() + n) 起算的毫秒數表示。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
清除鬧鐘 (具有指定名稱)。
參數
-
名稱
string 選填
要清除的鬧鐘名稱。預設為空字串。
-
回呼
函式 選填
callback參數如下所示：(wasCleared: boolean) => void
-
wasCleared
布林值
-
傳回
-
Promise<boolean>
Chrome 91 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有鬧鐘。
參數
-
回呼
函式 選填
callback參數如下所示：(wasCleared: boolean) => void
-
wasCleared
布林值
-
傳回
-
Promise<boolean>
Chrome 91 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
建立鬧鐘。在 alarmInfo 指定的時間附近，系統會觸發 onAlarm 事件。如果有其他鬧鐘的名稱與此鬧鐘相同 (如果未指定名稱，則為無名稱)，系統會取消該鬧鐘並以此鬧鐘取代。
為了減少使用者電腦的負載，Chrome 會將鬧鐘限制為每 30 秒最多一次，但可能會再延遲任意時間。也就是說，如果將 delayInMinutes 或 periodInMinutes 設為小於 0.5，系統將不會採用，並會顯示警告。when 可以設為「現在」後的 30 秒內，但不會在 30 秒內觸發鬧鐘。
為了協助您對應用程式或擴充功能進行偵錯，在您載入未解壓縮的應用程式或擴充功能時，鬧鐘觸發的頻率沒有限制。
參數
-
名稱
string 選填
用於識別鬧鐘的選用名稱。預設為空字串。
-
alarmInfo
說明鬧鐘應觸發的時機。初始時間必須由
when或delayInMinutes指定 (但不能同時指定)。如果設定periodInMinutes，鬧鐘會在初始事件發生後每隔periodInMinutes分鐘重複一次。如果重複鬧鐘未設定when或delayInMinutes，系統會使用periodInMinutes做為delayInMinutes的預設值。 -
回呼
函式 選填
Chrome 111 以上版本callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 111 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
擷取指定鬧鐘的詳細資料。
傳回
-
Promise<Alarm | undefined>
Chrome 91 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
取得所有鬧鐘的陣列。
傳回
-
Promise<Alarm[]>
Chrome 91 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。