chrome.alarms

Chrome 120: начиная с Chrome 120 минимальный интервал срабатывания сигнализации уменьшен с 1 минуты до 30 секунд. Чтобы сигнал срабатывал через 30 секунд, установите periodInMinutes: 0.5 .
Chrome 117: Начиная с Chrome 117, количество активных сигналов ограничено 500. Как только этот предел будет достигнут, chrome.alarms.create() завершится с ошибкой. При использовании обратного вызова будет установлен chrome.runtime.lastError . При использовании обещаний обещание будет отклонено.

Описание

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

Разрешения

alarms

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

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

Концепции и использование

Чтобы обеспечить надежное поведение, полезно понять, как ведет себя API.

Режим сна устройства

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

Упорство

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

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, установите пример Alarm API из репозитория chrome-extension-samples .

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

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

сервис-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
  });
});

Реагировать на сигнал тревоги

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

сервис-worker.js:

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

Типы

Alarm

Характеристики

• имя

  нить

  Название этого сигнала тревоги.

• периодInMinutes

  номер необязательно

  Если значение не равно нулю, сигнал тревоги является повторяющимся и сработает снова через periodInMinutes минут.

• запланированноевремя

  число

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

AlarmCreateInfo

Характеристики

• задержкавминутах

  номер необязательно

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

• периодInMinutes

  номер необязательно

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

• когда

  номер необязательно

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

Методы

clear()

Обещать

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

Удаляет сигнал тревоги с заданным именем.

Параметры

• имя

  строка необязательна

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

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (wasCleared: boolean) => void

  • былоОчищено

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

Возврат

• Обещание <логическое значение>

  Хром 91+

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

clearAll()

Обещать

chrome.alarms.clearAll(
  callback?: function,
)

Сбрасывает все сигналы тревоги.

Параметры

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (wasCleared: boolean) => void

  • былоОчищено

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

Возврат

• Обещание <логическое значение>

  Хром 91+

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

create()

Обещать

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Создает сигнал тревоги. Около времени, указанного в alarmInfo , запускается событие onAlarm . Если существует другой сигнал тревоги с таким же именем (или без имени, если оно не указано), он будет отменен и заменен этим сигналом тревоги.

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

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

Параметры

• имя

  строка необязательна

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

• сигнализацияИнформация

  ТревогаCreateInfo

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

• перезвонить

  функция необязательна

  Хром 111+

  Параметр callback выглядит так:

  () => void

Возврат

• Обещание<void>

  Хром 111+

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

get()

Обещать

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

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

Параметры

• имя

  строка необязательна

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

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (alarm?: Alarm) => void

  • тревога

    Сигнализация опционально

Возврат

• Обещание< Тревога | не определено>

  Хром 91+

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getAll()

Обещать

chrome.alarms.getAll(
  callback?: function,
)

Получает массив всех сигналов тревоги.

Параметры

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (alarms: Alarm[]) => void

  • сигналы тревоги

    Тревога []

Возврат

• Обещание< Тревога []>

  Хром 91+

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onAlarm

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

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

Параметры

• перезвонить

  функция

  Параметр callback выглядит так:

  (alarm: Alarm) => void

  • тревога

    Тревога