chrome.alarms

Описание

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

Разрешения

alarms

Манифест

Для использования API chrome.alarms необходимо указать разрешение "alarms" в манифесте :

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

Примеры

Приведенные ниже примеры демонстрируют, как использовать оповещение и реагировать на него. Чтобы попробовать этот 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,
  callback?: function,
): Promise<boolean>

Сбрасывает тревогу с указанным именем.

Параметры

  • имя

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

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

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

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

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

    (wasCleared: boolean) => void

    • был очищен

      логический

Возвраты

  • Promise<boolean>

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

clearAll()

Обещать
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

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

Параметры

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

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

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

    (wasCleared: boolean) => void

    • был очищен

      логический

Возвраты

  • Promise<boolean>

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

create()

Обещать
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

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

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

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

Параметры

  • имя

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

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

  • Информация об тревожной ситуации

    AlarmCreateInfo

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

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

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

    Chrome 111+

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 111+

    Обещание, которое выполняется после создания сигнала тревоги.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

get()

Обещать
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

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

Параметры

  • имя

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

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

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

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

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

    (alarm?: Alarm) => void

Возвраты

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

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getAll()

Обещать
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

Параметры

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

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

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

    (alarms: Alarm[]) => void

Возвраты

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

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onAlarm

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

Срабатывает по истечении времени ожидания сигнала тревоги. Полезно для страниц событий.

Параметры

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

    функция

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

    (alarm: Alarm) => void