chrome.alarms

Opis

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

Uprawnienia

alarms

Aby korzystać z 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 są uruchamiane co najwyżej raz, a następnie są 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ć uruchomiony.

Trwałość

Alerty zwykle są wyświetlane 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ę skrypt 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

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

    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.

  • persistAcrossSessions

    Wartość logiczna

    Oczekuje

    Określa, czy alarm ma być aktywny w kolejnych sesjach (po ponownym uruchomieniu przeglądarki).

  • scheduledTime

    liczba

    Czas, w którym alarm miał się włączyć, 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 opcja 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 zostanie uruchomiony tylko raz.

  • persistAcrossSessions

    wartość logiczna opcjonalna

    Oczekuje

    Określa, czy alarm ma być aktywny w kolejnych sesjach (po ponownym uruchomieniu przeglądarki). W Chrome domyślnie jest to wartość „true”, aby zachować zgodność z dotychczasowym działaniem, ale warto ustawić ją jawnie, aby zmaksymalizować zgodność między przeglądarkami.

  • 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 okolicach 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ą wartość. 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 uruchomi się 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 ustawisz 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

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

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[]>

Pobiera tablicę wszystkich alarmów.

Zwroty

  • Promise<Alarm[]>

    Chrome 91 lub nowsza

Wydarzenia

onAlarm

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

Uruchamiane po upłynięciu czasu alarmu. Przydatne na stronach wydarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (alarm: Alarm) => void