browser.alarms

Opis

Uprawnienia

Aby używać interfejsu browser.alarms API, 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ą 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 włączają się co najwyżej raz, a potem 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ł się pierwotnie włączyć.

Trwałość

Trwałość alarmu możesz kontrolować w momencie jego tworzenia za pomocą flagi persistAcrossSessions. Może mieć wartość true (utrzymywana do czasu aktualizacji rozszerzenia) lub false (usuwana po ponownym załadowaniu rozszerzenia lub ponownym uruchomieniu przeglądarki oraz po każdej aktualizacji rozszerzenia).

Inne przeglądarki i starsze wersje Chrome

Ta właściwość nie jest obsługiwana w innych przeglądarkach (problem) ani w wersjach Chrome starszych niż Chrome 150, w których jej działanie może być nieprzewidywalne. Dlatego najlepiej jest upewnić się, że ważne alarmy istnieją za każdym razem, gdy uruchamia się skrypt 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 na niego reagować. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Alarm API z repozytorium chrome-extension-samples.

Ustaw alarm

W przykładzie poniżej ustawiany jest alarm w skrypcie service worker, gdy zainstalowana zostanie nowa wersja 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),
  });
});

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

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

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

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

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

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