chrome.alarms

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu chrome.alarms API, aby zaplanować okresowe uruchamianie kodu lub uruchomienie go w określonym czasie w przyszłości.

Uprawnienia

alarms

Plik manifestu

Aby używać interfejsu API chrome.alarms, zadeklaruj uprawnienie "alarms" w pliku manifestu:

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

Przykłady

Poniższe przykłady pokazują, jak używać alarmu i jak na niego reagować. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Alarm API z repozytorium chrome-extension-samples.

Ustaw alarm

W tym przykładzie alarm jest ustawiany w skrypcie service worker po zainstalowaniu rozszerzenia:

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
  });
});

Reagowanie na alarm

W tym przykładzie ikona paska narzędzi działania jest ustawiana na podstawie nazwy alarmu, który się włączył.

service-worker.js:

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

Typy

Alarm

Właściwości

  • nazwa

    tekst

    Nazwa tego alarmu.

  • periodInMinutes

    number optional

    Jeśli nie jest pusta, alarm jest powtarzany i włączy się ponownie za periodInMinutes min.

  • persistAcrossSessions

    wartość logiczna

    Chrome 150+

    Określa, czy alarm powinien być zachowywany między sesjami (ponownymi uruchomieniami przeglądarki).

  • scheduledTime

    liczba

    Czas, na który zaplanowano uruchomienie tego alarmu, w milisekundach od początku epoki (np. Date.now() + n). Ze względu na wydajność alarm mógł zostać opóźniony o dowolną wartość.

AlarmCreateInfo

Właściwości

  • delayInMinutes

    number optional

    Czas w minutach, po którym powinno zostać wywołane zdarzenie onAlarm.

  • nazwa

    ciąg znaków opcjonalny

    Chrome 152 lub nowsza wersja

    Nazwa tego alarmu.

  • periodInMinutes

    number optional

    Jeśli ta opcja jest ustawiona, zdarzenie onAlarm powinno być wywoływane co periodInMinutes min po początkowym zdarzeniu określonym przez when lub delayInMinutes. Jeśli nie zostanie ustawiony, alarm włączy się tylko raz.

  • persistAcrossSessions

    boolean opcjonalne

    Chrome 150+

    Określa, czy alarm powinien być zachowywany między sesjami (ponownymi uruchomieniami przeglądarki). W Chrome domyślnie jest ustawiona wartość „true”, aby zachować zgodność z dotychczasowym działaniem, ale należy ustawić tę wartość jawnie, aby zmaksymalizować zgodność między przeglądarkami.

  • kiedy

    number optional

    Czas, w którym alarm powinien się uruchomić, podany w milisekundach od początku epoki (np. Date.now() + n).

Metody

clear()

Obietnica 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): Promise<boolean>

Usuwa alarm o podanej nazwie.

Parametry

  • nazwa

    ciąg znaków opcjonalny

    Nazwa alarmu, który chcesz wyłączyć. Domyślnie jest to pusty ciąg znaków.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

clearAll()

Obietnica 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean | undefined>

Usuwa wszystkie alarmy.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (wasCleared?: boolean) => void

    • wasCleared

      boolean opcjonalne

Zwroty

  • Promise<boolean | undefined>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

create()

Obietnica 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

Tworzy alarm. W pobliżu czasu określonego przez alarmInfo wywoływane jest zdarzenie onAlarm. Jeśli istnieje inny alarm o tej samej nazwie (lub bez nazwy, jeśli nie została podana), zostanie on anulowany i zastąpiony tym alarmem.

Aby zmniejszyć obciążenie komputera użytkownika, Chrome ogranicza alarmy do maksymalnie 1 na sekundę, ale może je opóźnić o dowolną wartość. Oznacza to, że ustawienie wartości delayInMinutes lub periodInMinutes na mniej niż 1 sekundę nie zostanie uwzględnione i spowoduje wyświetlenie ostrzeżenia. Wartość when można ustawić na mniej niż 1 sekundę po „teraz” bez ostrzeżenia, ale alarm nie zostanie uruchomiony przez co najmniej 1 sekundę.

Parametry

  • nazwa

    ciąg znaków opcjonalny

    Opcjonalna nazwa identyfikująca ten alarm. Domyślnie jest to pusty ciąg znaków.

  • alarmInfo

    AlarmCreateInfo

    Określa, kiedy alarm powinien się uruchomić. Czas początkowy musi być określony przez when lub delayInMinutes (ale nie przez oba te parametry). Jeśli ustawiono periodInMinutes, alarm będzie powtarzany co periodInMinutes min po pierwszym zdarzeniu. Jeśli w przypadku alarmu powtarzanego nie ustawiono ani when, ani delayInMinutes, jako domyślna wartość delayInMinutes zostanie użyta periodInMinutes.

  • callback

    function opcjonalne

    Chrome 111 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 111 lub nowsza wersja

    Obietnica, która zostanie spełniona po utworzeniu alarmu.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

get()

Obietnica 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

Pobiera szczegółowe informacje o określonym alarmie.

Parametry

  • nazwa

    ciąg znaków opcjonalny

    Nazwa alarmu do pobrania. Domyślnie jest to pusty ciąg znaków.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (alarm?: Alarm) => void

    • alarm

      Alarm opcjonalny

Zwroty

  • Promise<Alarm | undefined>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getAll()

Obietnica 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

Pobiera tablicę wszystkich alarmów.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (alarms: Alarm[]) => void

Zwroty

  • Promise<Alarm[]>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onAlarm

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

Uruchamiane po upływie czasu alarmu. Przydatne w przypadku stron wydarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (alarm: Alarm) => void