chrome.alarms

Описание

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

Разрешения

alarms

Манифест

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

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

Примеры

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

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

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

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

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

  • имя

    нить

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

  • периодВМинутах

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

    Если значение не равно нулю, сигнал тревоги повторяется и сработает снова через 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

    • был очищен

      булев

Возврат

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

    Хром 91+

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

clearAll()

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

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

Параметры

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

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

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

    (wasCleared: boolean) => void

    • был очищен

      булев

Возврат

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

    Хром 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 секунд после «now» без предупреждения, но будильник не будет срабатывать как минимум 30 секунд.

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

Параметры

  • имя

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

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

  • alarmInfo

    AlarmCreateInfo

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

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

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

    Хром 111+

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

    () => void

Возврат

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

    Хром 111+

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

get()

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

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

Параметры

  • имя

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

    Имя будильника, который нужно получить. По умолчанию — пустая строка.

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

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

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

    (alarm?: Alarm) => void

Возврат

  • Обещание< Сигнализация | не определено>

    Хром 91+

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

getAll()

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

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

Параметры

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

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

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

    (alarms: Alarm[]) => void

Возврат

  • Обещание< Сигнализация []>

    Хром 91+

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

События

onAlarm

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

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

Параметры

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

    функция

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

    (alarm: Alarm) => void