说明
使用 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
属性
-
name
字符串
此闹钟的名称。
-
periodInMinutes
number 可选
如果不是 null，则闹钟是重复闹钟，将在
periodInMinutes分钟后再次触发。 -
persistAcrossSessions
布尔值
Chrome 150 及更高版本闹钟是否应在会话（浏览器重启）之间保持。
-
scheduledTime
数值
此闹钟预定响铃的时间，以自纪元以来的毫秒数表示（例如
Date.now() + n）。出于性能原因，闹钟可能会在此时间之后延迟任意时长。
AlarmCreateInfo
属性
-
delayInMinutes
number 可选
onAlarm事件应在多长时间（以分钟为单位）后触发。 -
name
字符串 可选
Chrome 152 及更高版本此闹钟的名称。
-
periodInMinutes
number 可选
如果设置了此属性，则在
when或delayInMinutes指定的初始事件之后，onAlarm 事件应每隔periodInMinutes分钟触发一次。如果未设置，闹钟将仅响一次。 -
persistAcrossSessions
布尔值 （可选）
Chrome 150 及更高版本闹钟是否应在会话（浏览器重启）之间保持。在 Chrome 中，此值默认为 true，以与历史行为保持一致，但您应明确设置此值，以最大限度地提高跨浏览器兼容性。
-
什么时候
number 可选
闹钟应响起的时刻，以自纪元以来的毫秒数表示（例如
Date.now() + n）。
方法
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
清除具有指定名称的闹钟。
参数
-
name
字符串 可选
要清除的闹钟的名称。默认为空字符串。
返回
-
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 秒才会触发闹钟。
参数
-
name
字符串 可选
用于标识此闹钟的可选名称。默认为空字符串。
-
alarmInfo
描述闹钟应在何时触发。初始时间必须通过
when或delayInMinutes指定（但不能同时指定）。如果设置了periodInMinutes，则在初始事件发生后，警报将每隔periodInMinutes分钟重复一次。如果未为重复闹钟设置when或delayInMinutes，则periodInMinutes将用作delayInMinutes的默认值。
返回
-
承诺<void>
Chrome 111 及更高版本在闹钟创建后解析的 Promise。
参数
-
name
字符串 可选
要获取的闹钟的名称。默认为空字符串。
返回
-
Promise<Alarm | undefined>
Chrome 91 及更高版本
返回
-
Promise<Alarm[]>
Chrome 91 及更高版本