说明
使用 chrome.alarms API 可安排代码在指定时间或未来某个时间定期运行。
权限
alarms如需使用 chrome.alarms API，请在清单中声明 "alarms" 权限：
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
概念和使用
为确保可靠的行为，了解 API 的行为方式很有帮助。
设备休眠
设备处于休眠状态时，闹钟会继续运行。不过，闹钟不会唤醒设备。当设备唤醒时，所有错过的闹钟都会响铃。 重复闹钟最多会响一次，然后会根据指定周期重新安排闹钟，从设备唤醒时开始计时，不考虑自最初设置闹钟运行以来已经过去的时间。
持久性
警报通常会一直存在，直到扩展程序更新为止。不过，这无法保证，并且在浏览器重启时闹钟可能会被清除。因此，请确保每次服务工作线程启动时，该变量都存在。例如：
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { 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
属性
-
name
字符串
相应闹钟的名称。
-
periodInMinutes
number 可选
如果不为 null，则表示闹钟为重复闹钟，将在
periodInMinutes分钟后再次响铃。 -
scheduledTime
数值
相应闹钟预定触发的时间，以自纪元以来的毫秒数表示（例如
Date.now() + n）。出于性能方面的考虑，闹钟可能会延迟任意时长。
AlarmCreateInfo
属性
-
delayInMinutes
number 可选
在多长时间（以分钟为单位）后应触发
onAlarm事件。 -
periodInMinutes
number 可选
如果设置了该值，则在
when或delayInMinutes指定的初始事件之后，每隔periodInMinutes分钟应触发一次 onAlarm 事件。如果未设置，闹钟将仅响铃一次。 -
什么时候
number 可选
闹钟应响铃的时间，以自纪元以来的毫秒数表示（例如
Date.now() + n）。
方法
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
清除具有指定名称的闹钟。
参数
-
name
字符串 可选
要清除的闹钟的名称。默认为空字符串。
返回
-
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 秒才会触发闹钟。
为了帮助您调试应用或扩展程序，当您以未打包的形式加载应用或扩展程序时，闹钟的触发频率不受限制。
参数
-
name
字符串 可选
用于标识相应闹钟的可选名称。默认为空字符串。
-
alarmInfo
描述闹钟应在何时响铃。必须通过
when或delayInMinutes（但不能同时通过两者）指定初始时间。如果设置了periodInMinutes，闹钟会在初始事件发生后每隔periodInMinutes分钟重复一次。如果未为重复闹钟设置when或delayInMinutes，则periodInMinutes会用作delayInMinutes的默认值。
返回
-
Promise<void>
Chrome 111 及更高版本
参数
-
name
字符串 可选
要获取的闹钟的名称。默认为空字符串。
返回
-
Promise<Alarm | undefined>
Chrome 91 及更高版本
返回
-
Promise<Alarm[]>
Chrome 91 及更高版本