chrome.alarms

Opis

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

Uprawnienia

alarms

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

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

Pojęcia i wykorzystanie

Aby zapewnić niezawodne działanie, warto poznać sposób działania interfejsu API.

Uśpienie urządzenia

Alarmy nadal działają, gdy urządzenie jest uśpione. Alarm nie będzie jednak Wybudź urządzenie. Gdy urządzenie się wybudzi, zostaną uruchomione wszystkie nieodebrane alarmy. Powtarzające się alarmy zostaną uruchomione maksymalnie raz, a następnie zostaną ponownie zaplanowane za pomocą w określonym czasie, licząc od momentu wybudzenia urządzenia, bez uwzględniania dowolny czas, który upłynął od pierwotnie ustawionego alarmu.

Trwałość

Alarmy zwykle działają do czasu zaktualizowania rozszerzenia. Nie jest to jednak gwarantowane, a alarmy może zostać wyczyszczona po ponownym uruchomieniu przeglądarki. Dlatego rozważ ustawienie wartości w miejscu na dane. po utworzeniu alarmu, a następnie upewnij się, że istnieje on przy każdym uruchomieniu skryptu service worker. Na przykład:

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ periodInMinutes: 1 });
    }
  }
}

checkAlarmState();

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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