chrome.alarms

Описание

Используйте 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