browser.alarms

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

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

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

Pojęcia i użycie

Aby zapewnić niezawodne działanie, warto zrozumieć, jak działa interfejs API.

Uśpienie urządzenia

Alarmy działają, gdy urządzenie jest uśpione. Alarm nie wybudzi jednak urządzenia. Gdy urządzenie się wybudzi, zostaną uruchomione wszystkie pominięte alarmy. Powtarzające się alarmy będą uruchamiane co najwyżej raz, a następnie będą planowane ponownie z użyciem określonego okresu, zaczynając od momentu wybudzenia urządzenia, bez uwzględniania czasu, który upłynął od momentu, gdy alarm został pierwotnie ustawiony.

Trwałość

Trwałość alarmu możesz kontrolować podczas jego tworzenia za pomocą flagi persistAcrossSessions. Możesz ustawić wartość true (utrzymuje się do momentu aktualizacji rozszerzenia) lub false (jest usuwana, gdy rozszerzenie zostanie ponownie załadowane lub przeglądarka zostanie uruchomiona ponownie, a także przy każdej aktualizacji rozszerzenia).

Inne przeglądarki i wcześniejsze wersje Chrome

Ta właściwość nie jest obsługiwana w innych przeglądarkach (problem) ani w wersjach Chrome starszych niż Chrome 150, gdzie zachowanie może być nieprzewidywalne. Dlatego najlepiej jest upewnić się, że ważne alarmy istnieją przy każdym uruchomieniu skryptu service worker. Na przykład:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Jeśli alarm jest tworzony dynamicznie na podstawie działania użytkownika, możesz zapisać informację o jego utworzeniu w innym miejscu, aby w razie potrzeby móc go odtworzyć.

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 nowej wersji rozszerzenia:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

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:

browser.alarms.onAlarm.addListener((alarm) => {
  browser.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()

chrome.alarms.clear(
  name?: string,
): 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.

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowsza wersja

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

Usuwa wszystkie alarmy.

Zwroty

  • Promise<boolean | undefined>

    Chrome 91 lub nowsza wersja

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): 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.

Zwroty

  • thought Promise<void>

    Chrome 111 lub nowsza wersja

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

get()

chrome.alarms.get(
  name?: string,
): 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.

Zwroty

  • Promise<Alarm | undefined>

    Chrome 91 lub nowsza wersja

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

Pobiera tablicę wszystkich alarmów.

Zwroty

  • Promise<Alarm[]>

    Chrome 91 lub nowsza wersja

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