browser.alarms

Описание

Используйте chrome.alarms API, чтобы запланировать периодическое выполнение кода или его запуск в определенное время.

Разрешения

alarms

Чтобы использовать browser.alarms API, объявите разрешение "alarms" в манифесте:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Основные понятия и использование

Чтобы обеспечить надежную работу, полезно понимать, как работает API.

Спящий режим устройства

Будильники продолжают работать, когда устройство находится в спящем режиме. Однако будильник не выведет устройство из спящего режима. Когда устройство выйдет из спящего режима, пропущенные будильники сработают. Повторяющиеся будильники сработают не более одного раза, а затем будут перенесены на указанный период, начиная с момента пробуждения устройства, без учета времени, которое уже прошло с момента первоначальной установки будильника.

Сохранение

Вы можете управлять сохранением будильника при его создании с помощью флага persistAcrossSessions. Доступны значения true (сохраняется до обновления расширения) и false (удаляется при перезагрузке расширения, перезапуске браузера и обновлении расширения).

Другие браузеры и более ранние версии Chrome

Это свойство не поддерживается в других браузерах (проблема) и в версиях Chrome до 150, где поведение может быть непредсказуемым. Поэтому лучше всего проверять наличие важных оповещений при каждом запуске сервисного работника. Пример:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Если будильник создается динамически на основе действий пользователя, вы можете сохранить информацию о том, что будильник был создан в другом месте, чтобы знать, что его нужно воссоздать в случае необходимости.

Примеры

В примерах ниже показано, как использовать будильник и реагировать на него. Чтобы попробовать этот API, установите пример Alarm API из хранилища chrome-extension-samples.

Установить будильник

В следующем примере устанавливается будильник в сервисном воркере при установке новой версии расширения:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Как ответить на сигнал будильника

В примере ниже значок панели инструментов устанавливается на основе названия сработавшего будильника.

service-worker.js:

browser.alarms.onAlarm.addListener((alarm) => {
  browser.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Типы

Alarm

Свойства

  • name

    string

    Название этого будильника.

  • periodInMinutes

    number (необязательно)

    Если значение не равно null, будильник повторяется и сработает снова через periodInMinutes мин.

  • persistAcrossSessions

    Логическое значение

    Chrome 150+

    Указывает, должно ли оповещение сохраняться между сеансами (перезапусками браузера).

  • scheduledTime

    число

    Время, на которое было запланировано срабатывание оповещения, в миллисекундах с начала эпохи (например, Date.now() + n). По причинам, связанным с производительностью, оповещение может быть отложено на произвольное время.

AlarmCreateInfo

Свойства

  • delayInMinutes

    number (необязательно)

    Время в минутах, по истечении которого должно активироваться событие onAlarm.

  • name

    Строка (необязательно)

    Chrome 152 и более поздних версий

    Название этого будильника.

  • periodInMinutes

    number (необязательно)

    Если задано, событие onAlarm должно срабатывать каждые periodInMinutes мин. после исходного события, указанного в when или delayInMinutes. Если не задать дни, будильник сработает только один раз.

  • persistAcrossSessions

    Логическое значение (необязательно)

    Chrome 150+

    Указывает, должно ли оповещение сохраняться между сеансами (перезапусками браузера). В Chrome по умолчанию используется значение true, но мы рекомендуем задавать его явным образом, чтобы обеспечить совместимость с другими браузерами.

  • когда

    number (необязательно)

    Время, когда должен сработать будильник, в миллисекундах с начала отсчета (например, Date.now() + n).

Методы

clear()

browser.alarms.clear(
  name?: string,
): Promise<boolean>

Удаляет будильник с указанным названием.

Параметры

  • name

    Строка (необязательно)

    Название будильника, который нужно отключить. Значение по умолчанию – пустая строка.

Возвраты

  • Promise<boolean>

    Chrome 91+ browser.* начиная с Chrome 148

clearAll()

browser.alarms.clearAll(): Promise<boolean | undefined>

Удалить все будильники.

Возвраты

  • Promise<boolean | undefined>

    Chrome 91+ browser.* начиная с Chrome 148

create()

browser.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

Создает будильник. Событие onAlarm активируется в указанное время (alarmInfo). Если у вас уже есть будильник с таким же названием (или без названия, если оно не указано), он будет отменен и заменен новым.

Чтобы снизить нагрузку на компьютер пользователя, Chrome ограничивает частоту срабатывания будильников до одного раза в секунду, но может задерживать их на произвольное время. Если вы зададите для параметра delayInMinutes или periodInMinutes значение меньше одной секунды, оно не будет учитываться и вы увидите предупреждение. when можно установить менее чем за 1 секунду до текущего времени без предупреждения, но будильник сработает не ранее чем через 1 секунду.

Параметры

  • name

    Строка (необязательно)

    Необязательное название для идентификации этого будильника. Значение по умолчанию – пустая строка.

  • alarmInfo

    AlarmCreateInfo

    Описывает, когда должен сработать будильник. Начальное время должно быть указано с помощью when или delayInMinutes (но не обоих). Если задано значение periodInMinutes, будильник будет повторяться каждые periodInMinutes минут после первого срабатывания. Если для повторяющегося будильника не задано ни when, ни delayInMinutes, то для delayInMinutes по умолчанию используется periodInMinutes.

Возвраты

  • Promise<void>

    Chrome 111+ browser.* начиная с Chrome 148

    Promise, который разрешается после создания будильника.

get()

browser.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

Получает сведения об указанном будильнике.

Параметры

  • name

    Строка (необязательно)

    Название будильника, который нужно получить. Значение по умолчанию – пустая строка.

Возвраты

  • Promise<Alarm | undefined>

    Chrome 91+ browser.* начиная с Chrome 148

getAll()

browser.alarms.getAll(): Promise<Alarm[]>

Возвращает массив всех будильников.

Возвраты

  • Promise<Alarm[]>

    Chrome 91+ browser.* начиная с Chrome 148

События

onAlarm

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

Срабатывает, когда истекает время будильника. Полезно для страниц событий.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (alarm: Alarm) => void