說明
如要安排定期或日後指定時間執行程式碼,請使用 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 範例 Cloud Storage 也提供目錄同步處理功能
設定鬧鐘
下列範例會在安裝擴充功能時,在 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
編號 選填
如果設定這項政策,在
when
或delayInMinutes
指定的初始事件之後,系統每periodInMinutes
分鐘就會觸發一次 onAlarm 事件。如果未設定,鬧鐘只會觸發一次。 -
時段
編號 選填
觸發鬧鐘的時間,以毫秒為單位超過 Epoch 紀元時間,例如
Date.now() + n
。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
清除指定名稱的鬧鐘。
參數
-
名稱
string optional
要清除的鬧鐘名稱。預設為空字串。
-
回呼
函式 選用
callback
參數如下所示:(wasCleared: boolean) => void
-
wasCleared
布林值
-
傳回
-
Promise<boolean>
Chrome 91 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有鬧鐘。
參數
-
回呼
函式 選用
callback
參數如下所示:(wasCleared: boolean) => void
-
wasCleared
布林值
-
傳回
-
Promise<boolean>
Chrome 91 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
建立鬧鐘。接近 alarmInfo
指定的時間時,會觸發 onAlarm
事件。如果另一個鬧鐘使用相同的名稱 (或者無指定名稱),系統將取消該鬧鐘,並由這個鬧鐘取代。
為降低使用者電腦的負載,Chrome 將鬧鐘時間限制為每 30 秒最多一次,但可能會延遲任意數值。也就是說,系統不會遵循將 delayInMinutes
或 periodInMinutes
設為小於 0.5
的情況,且只會發出警告。when
可設為在「現在」後不到 30 秒實際上不會觸發鬧鐘觸發至少 30 秒
為協助您對應用程式或擴充功能進行偵錯,在您將應用程式或擴充功能解除封裝後,鬧鐘觸發頻率沒有限制。
參數
-
名稱
string optional
用於辨識這個鬧鐘的名稱。預設為空字串。
-
alarmInfo
說明鬧鐘的觸發時機。初始時間必須用
when
或delayInMinutes
指定 (但不能兩者都指定)。如果設定periodInMinutes
,則鬧鐘會在初始事件結束後每periodInMinutes
分鐘重複一次。如果未為週期性鬧鐘設定when
或delayInMinutes
,系統會使用periodInMinutes
做為delayInMinutes
的預設選項。 -
回呼
函式 選用
Chrome 111 以上版本callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 111 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
擷取指定鬧鐘的詳細資料。
傳回
-
Promise<Alarm |未定義>
Chrome 91 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
取得所有鬧鐘的陣列。
傳回
-
Promise<Alarm[]>
Chrome 91 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。