chrome.alarms

描述： 使用 chrome.alarms API 安排代码周期性地运行或者在将来的指定时间运行。
可用版本： 从 Chrome 22 开始支持。
权限： "alarms"
了解更多： 事件页面

摘要

类型
Alarm
方法
create − chrome.alarms.create(string name, object alarmInfo)
get − chrome.alarms.get(string name, function callback)
getAll − chrome.alarms.getAll(function callback)
clear − chrome.alarms.clear(string name, function callback)
clearAll − chrome.alarms.clearAll(function callback)
事件
onAlarm

类型

Alarm

属性
string name

该定时器的名称。

double scheduledTime

该定时器计划的触发时间，以纪元以来所经过的毫秒数为单位（例如 Date.now() + n）。由于性能原因，定时器可能会延迟至该时间后的任意时间。

double （可选）
periodInMinutes

如果不是 null 的话，该定时器会重复触发，每隔 periodInMinutes 分钟触发。

方法

create

chrome.alarms.create(string name, object alarmInfo)

创建定时器，在 alarmInfo 指定的时间前后将产生 alarms.onAlarm 事件。如果已经存在具有相同名称（或者如果没指定而没有名称）另一个定时器，它将会被取消，并由这一定时器取代。

为了降低用户计算机的资源占用，Chrome 浏览器将定时器限制为最多每 1 分钟一次，而且可能会推迟任意长度的时间。也就是说，将 delayInMinutes 或 periodInMinutes 设置为小于 1 的值不会被认可，并会导致警告，when 可以设置为当前时间后小于1分钟的值，但是定时器至少在 1 分钟内不会运行。

为了帮助您调试您的应用或扩展程序，当您以未打包的形式加载时，不会限制定时器产生的频率。

参数
string （可选）
name

标识该定时器的可选字符串，默认为空字符串。

object alarmInfo

描述定时器触发的时刻，初始时刻必须由 when 或者 delayInMinutes 中的某一个（但不能同时）指定。如果设置了 periodInMinutes，定时器将在初始事件后每隔 periodInMinutes 分钟重复。如果重复定时器的 when 或 delayInMinutes 都没有设置，periodInMinutes 将作为 delayInMinutes 的默认值。

double （可选）
when

定时器应该触发的时刻，以纪元以来所经过的毫秒数为单位（例如 Date.now() + n）。

double （可选）
delayInMinutes

以分钟为单位的时间长度，在指定时间之后将产生 alarms.onAlarm 事件。
double （可选）
periodInMinutes

如果设置了该属性，定时器将在由 when 或者 delayInMinutes 指定的初始时间后每隔 periodInMinutes 分钟触发。如果没有设置，定时器只会触发一次。

get

chrome.alarms.get(string name, function callback)

获取指定定时器的有关详情。

参数
string （可选）
name

要获取的定时器名称，默认为空字符串。

function callback

callback 参数应该是一个如下形式的函数：

function( Alarm alarm) {...};
Alarm （可选）
alarm

getAll

chrome.alarms.getAll(function callback)

获取包含所有定时器的数组。

参数
function callback

callback 参数应该是一个如下形式的函数：

function(array of Alarm alarms) {...};
array of Alarm alarms

clear

chrome.alarms.clear(string name, function callback)

清除指定名称的定时器。

参数
string （可选）
name

要清除的定时器名称，默认为空字符串。

function （可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean wasCleared) {...};
boolean wasCleared

clearAll

chrome.alarms.clearAll(function callback)

清除所有定时器。

参数
function （可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean wasCleared) {...};
boolean wasCleared

事件

onAlarm

当定时器到达时间时产生，对于事件页面很有用。

addListener

chrome.alarms.onAlarm.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function( Alarm alarm) {...};
Alarm alarm

到达时间的定时器。

示例扩展程序

  • Event Page Example – Demonstrates usage and features of the event page
  • Google Mail Checker – 显示 Google Mail 收件箱中的未读邮件数。点击该按钮还可以打开您的收件箱。