chrome.alarms

Opis

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

Uprawnienia

alarms

Aby korzystać z interfejsu chrome.alarms API, w pliku manifest zadeklaruj uprawnienie "alarms":

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

Pojęcia i zastosowanie

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

Uśpienie urządzenia

Alarmy będą działać, gdy urządzenie jest w stanie uśpienia. Alarm nie obudzi jednak urządzenia. Gdy urządzenie się obudzi, wszystkie przegapione alarmy zostaną uruchomione. Alarmy powtarzające się będą działać maksymalnie raz, a następnie zostaną zaplanowane na określony okres od momentu włączenia urządzenia, bez uwzględniania czasu, który upłynął od momentu ustawienia alarmu.

Trwałość

Alarmy zwykle pozostają aktywne do momentu zaktualizowania rozszerzenia. Nie ma jednak takiej gwarancji, a alarmy mogą zostać usunięte po ponownym uruchomieniu przeglądarki. Dlatego rozważ ustawienie wartości w magazynie, gdy tworzony jest alarm, a następnie upewnij się, że istnieje on za każdym razem, gdy uruchamia się Twój serwis 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 reagować. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Alarm API z repozytorium chrome-extension-samples.

Ustaw alarm

W tym przykładzie po zainstalowaniu rozszerzenia ustawiany jest alarm w usługach:

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
  });
});

Odpowiedź na alarm

W tym przykładzie ikona paska narzędzi akcji 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 równa null, alarm jest alarmem powtarzającym się i zostanie uruchomiony ponownie za periodInMinutes minut.

  • scheduledTime

    liczba

    Czas, w którym ten alarm miał zostać uruchomiony, w milisekundach od początku ery (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 ma nastąpić zdarzenie onAlarm.

  • periodInMinutes

    number opcjonalny

    Jeśli 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 zadziała 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()

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

Czyści alarm o danej nazwie.

Parametry

  • nazwa

    ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

clearAll()

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

Wyłącza wszystkie alarmy.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

create()

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

tworzy alarm. W okresie określonym przez parametr alarmInfo jest wywoływane zdarzenie onAlarm. Jeśli istnieje inny alarm o tej samej nazwie (lub bez nazwy, jeśli nie ma określonej nazwy), zostanie on anulowany i zastąpiony przez ten alarm.

Aby zmniejszyć obciążenie komputera użytkownika, Chrome ogranicza liczbę alarmów do maksymalnie 1 raz na 30 sekund, ale może je opóźnić o dowolną ilość sekund. Oznacza to, że ustawienie wartości delayInMinutes lub periodInMinutes na mniejszą niż 0.5 spowoduje wyświetlenie ostrzeżenia. when można ustawić na mniej niż 30 sekund po „teraz” bez ostrzeżenia, ale alarm nie zostanie uruchomiony przez co najmniej 30 sekund.

Aby ułatwić debugowanie aplikacji lub rozszerzenia, po rozpakowaniu nie ma limitu częstotliwości uruchamiania 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

    Określa, kiedy ma być włączony alarm. Czas początkowy musi być określony jako when lub delayInMinutes (ale nie obie wartości). Jeśli ustawisz wartość periodInMinutes, alarm będzie się powtarzać co periodInMinutes minut po początkowym zdarzeniu. Jeśli dla budzika powtarzającego nie ustawiono ani wartości when, ani delayInMinutes, jako domyślna wartość parametru delayInMinutes będzie używana wartość periodInMinutes.

  • wywołanie zwrotne

    function opcjonalny

    Chrome 111 lub nowszy

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 111 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

get()

Obietnice 
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

    function opcjonalny

    Parametr callback ma postać:

    (alarm?: Alarm) => void

    • alarm

      Alarm opcjonalny

Zwroty

  • Obietkwarzeczenie<Alarm | nieokreślony>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getAll()

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

Pobiera tablicę wszystkich alarmów.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (alarms: Alarm[]) => void

Zwroty

  • Promise<Alarm[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onAlarm

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

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (alarm: Alarm) => void