browser.alarms

Opis

Uprawnienia

Aby korzystać z interfejsu browser.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ść

Podczas tworzenia alarmu możesz określić jego trwałość za pomocą flagi persistAcrossSessions. Może mieć wartość true (utrzymywana do momentu 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 za każdym razem, gdy uruchamia się skrypt service worker, warto upewnić się, że ważne alarmy istnieją. 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 ustawiamy 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>

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,
)