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 事件，应在 when 或 delayInMinutes 指定的初始事件发生后，每 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 秒最多一次，但可能会以任意时长延迟。也就是说，如果将 delayInMinutes 或 periodInMinutes 设置为小于 0.5，则操作将不会遵循，并会导致警告。when 可以设置为“now”之后的 30 秒以内但不会触发警报至少 30 秒。

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

参数

  • name

    字符串（可选）

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

  • alarmInfo

    AlarmCreateInfo

    说明警报应何时触发。初始时间必须由 when 或 delayInMinutes 指定（但不能同时由两者指定）。如果您设置了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