chrome.alarms

Opis

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

Uprawnienia

alarms

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

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

Pojęcia i zastosowanie

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

Uśpienie urządzenia

Alarmy działają nadal, gdy urządzenie jest uśpione. Alarm nie wybudzi jednak urządzenia. Gdy urządzenie się wybudzi, uruchomią się wszystkie alarmy, które zostały pominięte. Powtarzające się alarmy będą włączane co najwyżej raz, a następnie będą ponownie planowane z użyciem określonego okresu, począwszy od momentu, w którym urządzenie się włączy, bez uwzględniania czasu, który upłynął od momentu, w którym alarm miał zostać pierwotnie włączony.

Trwałość

Alarmy zwykle są aktywne do momentu zaktualizowania rozszerzenia. Nie jest to jednak gwarantowane, a alarmy mogą zostać wyczyszczone po ponownym uruchomieniu przeglądarki. Dlatego upewnij się, że jest on dostępny za każdym razem, gdy uruchamia się service worker. Na przykład:

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

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

checkAlarmState();

Przykłady

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

Ustaw alarm

Ten przykład ustawia alarm w usłudze 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

    ciąg znaków

    Nazwa tego alarmu.

  • periodInMinutes

    number opcjonalny

    Jeśli nie jest to wartość null, alarm jest powtarzany i włączy się ponownie za periodInMinutes minut.

  • scheduledTime

    liczba

    Czas, w którym alarm miał zostać uruchomiony, 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 opcjonalny

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

  • periodInMinutes

    number opcjonalny

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

  • kiedy

    number opcjonalny

    Czas, w którym ma się włączyć alarm, 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 do wyczyszczenia. Domyślnie jest to pusty ciąg znaków.

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowsza

clearAll()

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

Usuwa wszystkie alarmy.

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowsza

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 określona), zostanie on anulowany i zastąpiony tym alarmem.

Aby zmniejszyć obciążenie urządzenia użytkownika, Chrome ogranicza liczbę alarmów do maksymalnie 1 na 30 sekund, ale może je opóźnić o dowolną ilość czasu. Oznacza to, że ustawienie wartości delayInMinutes lub periodInMinutes mniejszej niż 0.5 nie zostanie uwzględnione i spowoduje wyświetlenie ostrzeżenia. when można ustawić na czas krótszy niż 30 sekund od „teraz” bez ostrzeżenia, ale alarm nie zostanie włączony przez co najmniej 30 sekund.

Aby ułatwić Ci debugowanie aplikacji lub rozszerzenia, po załadowaniu go w formie rozpakowanej nie ma ograniczeń co do częstotliwości wywoływania alarmu.

Parametry

  • nazwa

    ciąg znaków opcjonalny

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

  • alarmInfo

    AlarmCreateInfo

    Opisuje, kiedy ma się włączyć alarm. Czas początkowy musi być określony przez when lub delayInMinutes (ale nie oba). Jeśli ustawiona jest wartość periodInMinutes, alarm będzie się powtarzać co periodInMinutes minut po pierwszym zdarzeniu. Jeśli w przypadku powtarzającego się alarmu nie ustawiono wartości when ani delayInMinutes, domyślnie używana jest wartość periodInMinutes.delayInMinutes

Zwroty

  • Promise<void>

    Chrome 111 lub nowsza

get()

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

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.

Zwroty

  • Promise<Alarm | undefined>

    Chrome 91 lub nowsza

getAll()

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

Zwraca tablicę wszystkich alarmów.

Zwroty

  • Promise<Alarm[]>

    Chrome 91 lub nowsza

Wydarzenia

onAlarm

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

Uruchamiane po upływie czasu alarmu. Przydatne na stronach wydarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (alarm: Alarm) => void