chrome.alarms

Описание

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

Разрешения

alarms

Манифест

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

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

Примеры

Следующие примеры показывают, как использовать сигнал тревоги и реагировать на него. Чтобы попробовать этот 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
  });
});

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

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

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

сервис-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+

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

clearAll()

Обещать

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

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

Параметры

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

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

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

  (wasCleared: boolean) => void

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

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

Возврат

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

  Хром 91+

  Промисы поддерживаются только для Manifest 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+

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

get()

Обещать

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

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

Параметры

• имя

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

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

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

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

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

  (alarm?: Alarm) => void

  • тревога

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

Возврат

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

  Хром 91+

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

getAll()

Обещать

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

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

Параметры

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

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

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

  (alarms: Alarm[]) => void

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

    Тревога []

Возврат

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

  Хром 91+

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

События

onAlarm

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

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

Параметры

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

  функция

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

  (alarm: Alarm) => void

  • тревога

    Тревога