说明
您可以使用 chrome.alarms API 安排代码定期运行，或在未来的指定时间运行。
权限
alarms清单
如需使用 chrome.alarms API，请在 清单中声明 "alarms" 权限：
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
示例
以下示例展示了如何使用闹钟以及如何响应闹钟。如需试用此 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
数值 （可选）
如果不为 null，则闹钟为重复闹钟，并会在
periodInMinutes分钟后再次响起。 -
persistAcrossSessions
布尔值
待处理闹钟是否应在会话（浏览器重启）之间保持不变。
-
scheduledTime
数值
此闹钟计划响起的时间，以自纪元以来的毫秒数表示（例如
Date.now() + n）。出于性能考虑，闹钟可能会延迟任意时长。
AlarmCreateInfo
属性
-
delayInMinutes
数值 （可选）
onAlarm事件应在多少分钟后触发。 -
periodInMinutes
数值 （可选）
如果设置了此属性，则 onAlarm 事件应在
when或delayInMinutes指定的初始事件之后每periodInMinutes分钟触发一次。如果未设置此属性，闹钟将仅触发一次。 -
persistAcrossSessions
布尔值（可选）
待处理闹钟是否应在会话（浏览器重启）之间保持不变。在 Chrome 中，此属性默认为 true 以匹配历史行为，但您应明确设置此属性，以最大限度地提高跨浏览器的兼容性。
-
when
数值 （可选）
闹钟应响起的时间，以自纪元以来的毫秒数表示（例如
Date.now() + n）。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
): Promise<boolean>
清除具有指定名称的闹钟。
参数
-
name
字符串 （可选）
要清除的闹钟的名称。默认为空字符串。
-
callback
函数（可选）
callback参数如下所示：(wasCleared: boolean) => void
-
wasCleared
布尔值
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。
clearAll()
chrome.alarms.clearAll(
callback?: function,
): Promise<boolean>
清除所有闹钟。
参数
-
callback
函数（可选）
callback参数如下所示：(wasCleared: boolean) => void
-
wasCleared
布尔值
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
): Promise<void>
创建闹钟。在 alarmInfo 指定的时间附近，系统会触发 onAlarm 事件。如果存在另一个同名闹钟（如果未指定名称，则没有名称），则该闹钟将被取消并替换为此闹钟。
为了减少用户机器上的负载，Chrome 将闹钟限制为最多每 30 秒触发一次，但可能会延迟任意时长。也就是说，将 delayInMinutes 或 periodInMinutes 设置为小于 0.5 将不会生效，并会导致警告。您可以将 when 设置为小于“现在”后 30 秒，而不会收到警告，但实际上至少 30 秒后闹钟才会触发。
为了帮助您调试应用或扩展程序，当您以未打包的方式加载应用或扩展程序时，alarm 的触发频率不受限制。
参数
-
name
字符串 （可选）
用于标识此闹钟的可选名称。默认为空字符串。
-
alarmInfo
描述闹钟应何时触发。初始时间必须由
when或delayInMinutes（但不能同时由两者）指定。如果设置了periodInMinutes，则闹钟将在初始事件之后每periodInMinutes分钟重复一次。如果未为重复闹钟设置when或delayInMinutes，则periodInMinutes将用作delayInMinutes的默认值。 -
callback
函数（可选）
Chrome 111 及更高版本callback参数如下所示：() => void
返回
-
Promise<void>
Chrome 111 及更高版本闹钟创建后解析的 Promise。
Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。
get()
chrome.alarms.get(
name?: string,
callback?: function,
): Promise<Alarm | undefined>
检索有关指定闹钟的详细信息。
参数
返回
-
Promise<Alarm | undefined>
Chrome 91 及更高版本Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。
返回
-
Promise<Alarm[]>
Chrome 91 及更高版本Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。