chrome.alarms

说明

使用 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 事件,应在 whendelayInMinutes 指定的初始事件发生后,每 periodInMinutes 分钟触发一次。如果不设置,闹钟只会触发一次。

  • 什么时候

    编号(选填

    闹钟应触发的时间,以从公元纪年开始计算的毫秒数表示(例如 Date.now() + n)。

方法

clear()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

清除具有指定名称的闹钟。

参数

  • name

    字符串(可选)

    要清除的闹钟的名称。默认为空字符串。

  • callback

    函数(可选)

    callback 参数如下所示:

    (wasCleared: boolean) => void

    • wasCleared

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

clearAll()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.alarms.clearAll(
  callback?: function,
)

清除所有闹钟。

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    (wasCleared: boolean) => void

    • wasCleared

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

create()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

创建闹钟。在 alarmInfo 指定的时间附近会触发 onAlarm 事件。如果存在其他同名的闹钟(如果未指定名称,则没有指定名称),该闹钟将被取消并替换为该闹钟。

为了减少用户计算机的负载,Chrome 将闹钟限制为每 30 秒最多一次,但可能会以任意时长延迟。也就是说,如果将 delayInMinutesperiodInMinutes 设置为小于 0.5,则操作将不会遵循,并会导致警告。when 可以设置为“now”之后的 30 秒以内但不会触发警报至少 30 秒。

为帮助您调试应用或扩展程序,在解压缩应用或扩展程序后,对闹钟的触发频率没有限制。

参数

  • name

    字符串(可选)

    用于标识此闹钟的可选名称。默认为空字符串。

  • alarmInfo

    说明警报应何时触发。初始时间必须由 whendelayInMinutes 指定(但不能同时由两者指定)。如果您设置了periodInMinutes,闹钟将在初始事件发生后每 periodInMinutes 分钟重复一次。如果重复闹钟既没有设置 when,也没有设置 delayInMinutes,则 delayInMinutes 会默认使用 periodInMinutes

  • callback

    函数(可选)

    Chrome 111 及更高版本

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 111 及更高版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

get()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.alarms.get(
  name?: string,
  callback?: function,
)

检索指定闹钟的详细信息。

参数

  • name

    字符串(可选)

    要获取的闹钟的名称。默认为空字符串。

  • callback

    函数(可选)

    callback 参数如下所示:

    (alarm?: Alarm) => void

返回

  • Promise&lt;Alarm |未定义>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.alarms.getAll(
  callback?: function,
)

获取包含所有闹钟的数组。

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    (alarms: Alarm[]) => void

返回

  • Promise<警报[]>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

在闹钟响起时触发。对于活动页面很有用。

参数

  • callback

    函数

    callback 参数如下所示:

    (alarm: Alarm) => void