说明
使用 chrome.alarms API 安排代码定期运行或在未来的指定时间运行。
权限
alarms如需使用 chrome.alarms API，请在清单中声明 "alarms" 权限：
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
概念和用法
为确保行为的可靠性，了解 API 的行为方式会很有帮助。
设备休眠
当设备处于休眠状态时，闹钟会继续运行。但是，闹钟不会 唤醒设备。当设备唤醒时，将触发任何错过的闹钟。 重复闹钟最多触发一次，然后使用 从设备唤醒时开始计算的指定时间段，不考虑 自闹钟最初设置为运行后已过去的任何时间。
持久性
闹钟通常持续到扩展程序更新为止。不过，我们无法保证这一点 在浏览器重新启动时可能会被清除。因此，请考虑在存储空间中设置一个值 ，然后确保它在每次 Service Worker 启动时都存在。例如：
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 中的 chrome-extension-samples 存储库
设置闹钟
以下示例会在安装扩展程序时在 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
编号（选填）
如果不为 null，则该闹钟是重复闹钟，将在
periodInMinutes分钟后再次触发。 -
scheduledTime
number
此闹钟的预定触发时间，以从公元纪年开始计算的毫秒数表示（例如
Date.now() + n）。出于性能方面的原因，闹钟可能会延迟任意时长。
AlarmCreateInfo
属性
-
delayInMinutes
编号（选填）
onAlarm事件应在多长时间后触发（以分钟为单位）。 -
periodInMinutes
编号（选填）
如果设置了 onAlarm 事件，应在
when或delayInMinutes指定的初始事件发生后，每periodInMinutes分钟触发一次。如果不设置，闹钟只会触发一次。 -
什么时候
编号（选填）
闹钟应触发的时间，以从公元纪年开始计算的毫秒数表示（例如
Date.now() + n）。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
清除具有指定名称的闹钟。
参数
-
name
字符串（可选）
要清除的闹钟的名称。默认为空字符串。
-
callback
函数（可选）
callback参数如下所示：(wasCleared: boolean) => void
-
wasCleared
布尔值
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有闹钟。
参数
-
callback
函数（可选）
callback参数如下所示：(wasCleared: boolean) => void
-
wasCleared
布尔值
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
创建闹钟。在 alarmInfo 指定的时间附近会触发 onAlarm 事件。如果存在其他同名的闹钟（如果未指定名称，则没有指定名称），该闹钟将被取消并替换为该闹钟。
为了减少用户计算机的负载，Chrome 将闹钟限制为每 30 秒最多一次，但可能会以任意时长延迟。也就是说，如果将 delayInMinutes 或 periodInMinutes 设置为小于 0.5，则操作将不会遵循，并会导致警告。when 可以设置为“now”之后的 30 秒以内但不会触发警报至少 30 秒。
为帮助您调试应用或扩展程序，在解压缩应用或扩展程序后，对闹钟的触发频率没有限制。
参数
-
name
字符串（可选）
用于标识此闹钟的可选名称。默认为空字符串。
-
alarmInfo
说明警报应何时触发。初始时间必须由
when或delayInMinutes指定（但不能同时由两者指定）。如果您设置了periodInMinutes，闹钟将在初始事件发生后每periodInMinutes分钟重复一次。如果重复闹钟既没有设置when，也没有设置delayInMinutes，则delayInMinutes会默认使用periodInMinutes。 -
callback
函数（可选）
Chrome 111 及更高版本callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 111 及更高版本Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
检索指定闹钟的详细信息。
参数
返回
-
Promise<Alarm |未定义>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
获取包含所有闹钟的数组。