说明
使用 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 代码库安装 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
string
此闹钟的名称。
-
periodInMinutes
数字可选
如果不为 null,该闹钟是重复性闹钟,将在
periodInMinutes
分钟后再次触发。 -
scheduledTime
number
此闹钟预定触发的时间,以纪元过后的毫秒数表示(例如
Date.now() + n
)。出于性能方面的原因,闹钟可能会延迟任意时长。
AlarmCreateInfo
属性
-
delayInMinutes
数字可选
onAlarm
事件应在多长时间后触发(以分钟为单位)。 -
periodInMinutes
数字可选
如果已设置,则 onAlarm 事件应在
when
或delayInMinutes
指定的初始事件发生后每periodInMinutes
分钟触发一次。如果未设置,则闹钟仅触发一次。 -
when
数字可选
闹钟应触发的时间,以从公元纪年开始计算的毫秒数表示(例如
Date.now() + n
)。
方法
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
清除具有指定名称的闹钟。
参数
-
name
字符串(可选)
要清除的闹钟的名称。默认为空字符串。
-
callback
函数(可选)
callback
参数如下所示:(wasCleared: boolean) => void
-
wasCleared
boolean
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
清除所有闹钟。
参数
-
callback
函数(可选)
callback
参数如下所示:(wasCleared: boolean) => void
-
wasCleared
boolean
-
返回
-
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
可以设置为“现在”之后不到 30 秒,而不发出警告,但实际上不会导致闹钟至少触发 30 秒。
为了帮助您调试应用或扩展程序,在解压缩后,对闹钟的触发频率没有限制。
参数
-
name
字符串(可选)
用于标识此闹钟的可选名称。默认为空字符串。
-
alarmInfo
说明闹钟应何时触发。初始时间必须通过
when
或delayInMinutes
(但不能同时用两者)指定。如果设置了periodInMinutes
,闹钟将在初始事件后每periodInMinutes
分钟重复一次。如果when
和delayInMinutes
均未设置重复闹钟,则将periodInMinutes
用作delayInMinutes
的默认值。 -
callback
函数(可选)
Chrome 111 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 111 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
检索有关指定闹钟的详细信息。
参数
返回
-
Promise<Alarm | undefined>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getAll()
chrome.alarms.getAll(
callback?: function,
)
获取包含所有闹钟的数组。
返回
-
Promise<闹钟[]>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。