Описание
Используйте API chrome.alarms для планирования периодического выполнения кода или его запуска в указанное время в будущем.
Разрешения
alarms Для использования API chrome.alarms необходимо указать разрешение "alarms" в манифесте :
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Понятия и применение
Для обеспечения надежной работы полезно понимать, как функционирует API.
спящий режим устройства
Будильники продолжают работать, пока устройство находится в спящем режиме. Однако будильник не разбудит устройство. Когда устройство проснется, все пропущенные будильники сработают. Повторяющиеся будильники сработают максимум один раз, а затем будут перенесены на другой период, начиная с момента пробуждения устройства, без учета времени, прошедшего с момента первоначальной установки будильника.
Упорство
Обычно оповещения сохраняются до обновления расширения. Однако это не гарантируется, и оповещения могут исчезнуть при перезапуске браузера. Поэтому убедитесь, что расширение существует каждый раз при запуске вашего сервис-воркера. Например:
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
Примеры
Приведенные ниже примеры демонстрируют, как использовать оповещение и реагировать на него. Чтобы попробовать этот API, установите пример Alarm API из репозитория chrome-extension-samples .
Установить будильник
В следующем примере в сервис-воркере устанавливается оповещение при установке расширения:
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
Характеристики
- имя
нить
Название этого сигнала тревоги.
- периодВминутах
число необязательно
Если значение не равно null, сигнал тревоги является повторяющимся и сработает снова через
periodInMinutesминут. - запланированное время
число
Время, когда должен был сработать этот будильник, в миллисекундах после начала эпохи (например
Date.now() + n). В целях повышения производительности срабатывание будильника могло быть отложено на произвольное время сверх этого.
AlarmCreateInfo
Характеристики
- delayInMinutes
число необязательно
Продолжительность времени в минутах, по истечении которого должно сработать событие
onAlarm. - периодВминутах
число необязательно
Если задано, событие onAlarm должно срабатывать каждые
periodInMinutesминут после первоначального события, указанного параметрамиwhenилиdelayInMinutes. Если не задано, сигнал тревоги сработает только один раз. - когда
число необязательно
Время, в которое должен сработать будильник, в миллисекундах после начала эпохи (например,
Date.now() + n).
Методы
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
Сбрасывает тревогу с указанным именем.
Параметры
- имя
строка необязательный
Название тревожного сигнала, который нужно отключить. По умолчанию используется пустая строка.
Возвраты
Promise<boolean>
Chrome 91+
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
Сбрасывает все сигналы тревоги.
Возвраты
Promise<boolean>
Chrome 91+
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
Создает будильник. Примерно в указанное в alarmInfo время (или несколько времени) срабатывает событие onAlarm . Если существует другой будильник с тем же именем (или без имени, если оно не указано), он будет отменен и заменен этим будильником.
Чтобы снизить нагрузку на компьютер пользователя, Chrome ограничивает срабатывание будильников максимум одним разом в 30 секунд, но может задерживать их на произвольное расстояние больше. То есть, если установить delayInMinutes или periodInMinutes меньше 0.5 , они не будут учтены и вызовут предупреждение. when можно установить меньше 30 секунд после "сейчас" без предупреждения, но это не приведет к срабатыванию будильника как минимум в течение 30 секунд.
Чтобы помочь вам в отладке вашего приложения или расширения, после его распаковки нет ограничений на частоту срабатывания будильника.
Параметры
- имя
строка необязательный
Необязательное имя для идентификации этого сигнала тревоги. По умолчанию используется пустая строка.
- Информация об тревожной ситуации
Указывает, когда должен сработать сигнал тревоги. Начальное время должно быть указано либо параметром
when, либоdelayInMinutes(но не обоими одновременно). Если задан параметрperiodInMinutes, сигнал тревоги будет повторяться каждыеperiodInMinutesминут после первоначального события. Если для повторяющегося сигнала тревоги не заданы ниwhen, ниdelayInMinutes, в качестве значения по умолчанию дляdelayInMinutesиспользуетсяperiodInMinutes.
Возвраты
Обещание<пустота>
Chrome 111+Обещание, которое выполняется после создания сигнала тревоги.
get()
chrome.alarms.get(
name?: string,
): Promise<Alarm | undefined>
Получает подробную информацию об указанном сигнале тревоги.
Параметры
- имя
строка необязательный
Название получаемого сигнала тревоги. По умолчанию используется пустая строка.
Возвраты
Обещание< Тревога | не определено>
Chrome 91+
Возвраты
Обещание< Тревога []>
Chrome 91+