chrome.alarms

Opis

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

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 zareagować. Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs Alarm API ze strony chrome-extension-samples. z repozytorium.

Ustaw alarm

Ten przykład pozwala ustawić alarm 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 przykładzie poniżej ustawiamy ikonę na pasku narzędzi działań na podstawie nazwy uruchomionego alarmu.

service-worker.js:

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

Typy

Alarm

Właściwości

  • nazwa

    ciąg znaków

    Nazwa tego alarmu.

  • periodInMinutes

    liczba opcjonalnie

    Jeśli nie ma wartości null, alarm jest powtarzający się i zostanie ponownie uruchomiony za periodInMinutes min.

  • scheduledTime

    liczba

    Godzina, na którą ten alarm miał być uruchomiony, w milisekundach po zakończeniu epoki (np. Date.now() + n). Ze względu na wydajność alarm mógł zostać opóźniony o dowolną kwotę.

AlarmCreateInfo

Właściwości

  • delayInMinutes

    liczba opcjonalnie

    Czas (w minutach), po którym powinno być uruchamiane zdarzenie onAlarm.

  • periodInMinutes

    liczba opcjonalnie

    Jeśli jest ustawione, zdarzenie onAlarm powinno być uruchamiane co periodInMinutes min po zdarzeniu początkowym określonym przez parametr when lub delayInMinutes. Jeśli nie zostanie ustawiony, alarm uruchomi się tylko raz.

  • kiedy

    liczba opcjonalnie

    Czas, w którym powinien zostać uruchomiony alarm, wyrażony w milisekundach po zakończeniu epoki (np. Date.now() + n).

Metody

clear()

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

Czyści alarm o podanej nazwie.

Parametry

  • nazwa

    ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

clearAll()

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

Usuwa wszystkie alarmy.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

create()

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

Tworzy alarm. W pobliżu godzin określonych przez alarmInfo wywoływane jest zdarzenie onAlarm. Jeśli pojawi się inny alarm o tej samej nazwie (lub bez niej, jeśli nie zostanie podana), zostanie on anulowany i zastąpiony tym alarmem.

Aby zmniejszyć obciążenie komputera użytkownika, Chrome ogranicza alarmy nie częściej niż co 30 sekund, ale może opóźniać ich działanie o dowolną kwotę. Oznacza to, że ustawienie wartości delayInMinutes lub periodInMinutes na mniejsze niż 0.5 nie zostanie uwzględnione i powoduje wyświetlenie ostrzeżenia. W przypadku parametru when można ustawić wartość „czasem krótszym niż 30 sekund” od czasu „teraz” bez ostrzeżenia, ale nie spowoduje uruchomienia alarmu na co najmniej 30 sekund.

Aby ułatwić debugowanie aplikacji lub rozszerzenia po rozpakowaniu, nie ma ograniczeń co do częstotliwości uruchamiania alarmu.

Parametry

  • nazwa

    ciąg znaków opcjonalny

    Opcjonalna nazwa tego alarmu. Domyślnie jest to pusty ciąg znaków.

  • alarmInfo

    AlarmCreateInfo

    Opisuje, kiedy ma się uruchomić alarm. Czas początkowy musi być określony przez when lub delayInMinutes (ale nie obie). Jeśli ustawiona jest zasada periodInMinutes, alarm będzie się powtarzał co periodInMinutes min po pierwszym wydarzeniu. Jeśli powtarzający się alarm nie jest ustawiony na when ani delayInMinutes, domyślną wartością w delayInMinutes jest periodInMinutes.

  • wywołanie zwrotne

    funkcja optional

    Chrome w wersji 111 lub nowszej .

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 111 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

get()

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

Pobiera szczegóły określonego alarmu.

Parametry

  • nazwa

    ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (alarm?: Alarm) => void

    • alarm

      Alarm opcjonalny

Zwroty

  • Promise&lt;Alarm | niezdefiniowane>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getAll()

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

Pobiera tablicę wszystkich alarmów.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (alarms: Alarm[]) => void

Zwroty

  • Obietnica<Alarm[]>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onAlarm

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

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (alarm: Alarm) => void