chrome.alarms

Opis

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

Uprawnienia

alarms

Aby korzystać z interfejsu API chrome.alarms, 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 pominięte alarmy. Alarmy powtarzające się uruchomią się co najwyżej raz, a następnie zostaną ponownie zaplanowane z określonym okresem, począwszy od momentu wybudzenia urządzenia, bez uwzględniania czasu, który upłynął od pierwotnego ustawienia alarmu.

Trwałość

Trwałość alarmu możesz kontrolować w momencie jego tworzenia za pomocą flagi persistAcrossSessions. Można ją ustawić na true (alarm będzie działać do czasu aktualizacji rozszerzenia) lub false (alarm zostanie wyczyszczony, jeśli rozszerzenie zostanie ponownie załadowane lub przeglądarka zostanie ponownie uruchomiona, a także 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 zachowanie 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 chrome.alarms.get("my-alarm");

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

checkAlarmState();

Jeśli alarm jest tworzony dynamicznie na podstawie działania użytkownika, możesz zapisać informację o utworzeniu alarmu w innym miejscu, aby w razie potrzeby go odtworzyć.

Przykłady

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

Ustaw alarm

Poniższy przykład ustawia alarm w skrypcie service worker, gdy zainstalowana zostanie nowa wersja rozszerzenia:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Reagowanie na alarm

Poniższy przykład ustawia ikonę paska narzędzi działania 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

    liczba opcjonalna

    Jeśli nie jest to wartość null, alarm jest powtarzany i zostanie ponownie uruchomiony po periodInMinutes minutach.

  • persistAcrossSessions

    Wartość logiczna

    Oczekuje

    Czy alarm ma być trwały w różnych sesjach (ponowne uruchomienia przeglądarki).

  • scheduledTime

    liczba

    Czas, o którym zaplanowano uruchomienie tego alarmu, w milisekundach od początku epoki (np. Date.now() + n). Ze względu na wydajność alarm może być opóźniony o dowolną wartość.

AlarmCreateInfo

Właściwości

  • delayInMinutes

    liczba opcjonalna

    Czas w minutach, po którym ma się uruchomić zdarzenie onAlarm.

  • periodInMinutes

    liczba opcjonalna

    Jeśli ta opcja jest ustawiona, zdarzenie onAlarm powinno się uruchamiać co periodInMinutes minut po początkowym zdarzeniu określonym przez when lub delayInMinutes. Jeśli ta opcja nie jest ustawiona, alarm uruchomi się tylko raz.

  • persistAcrossSessions

    wartość logiczna opcjonalna

    Oczekuje

    Czy alarm ma być trwały w różnych sesjach (ponowne uruchomienia przeglądarki). W Chrome domyślnie jest to wartość true, aby zachować dotychczasowe działanie, ale aby zmaksymalizować zgodność z różnymi przeglądarkami, należy ustawić tę wartość wyraźnie.

  • kiedy

    liczba opcjonalna

    Czas, o którym ma się uruchomić 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 usunięcia. Domyślnie jest to pusty ciąg znaków.

Zwroty

  • Promise<boolean>

    Chrome 91+

clearAll()

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

Usuwa wszystkie alarmy.

Zwroty

  • Promise<boolean>

    Chrome 91+

create()

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

Tworzy alarm. W pobliżu czasu określonego przez alarmInfo uruchamia się 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 komputera użytkownika, Chrome ogranicza alarmy do maksymalnie 1 alarmu co 30 sekund, ale może je opóźnić o dowolną wartość. Oznacza to, że ustawienie delayInMinutes lub periodInMinutes na wartość mniejszą niż 0.5 nie będzie respektowane i spowoduje ostrzeżenie. Wartość when można ustawić na mniej niż 30 sekund po „teraz” bez ostrzeżenia, ale alarm nie uruchomi się przez co najmniej 30 sekund.

Aby ułatwić debugowanie aplikacji lub rozszerzenia, gdy zostało ono wczytane bez rozpakowania, nie ma ograniczenia 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 się uruchomić alarm. Początkowy czas musi być określony przez when lub delayInMinutes (ale nie oba). Jeśli ustawisz periodInMinutes, alarm będzie się powtarzać co periodInMinutes minut po początkowym zdarzeniu. Jeśli dla alarmu powtarzającego się nie ustawisz when ani delayInMinutes, periodInMinutes będzie używane jako domyślna wartość delayInMinutes.

Zwroty

  • Promise<void>

    Chrome 111+

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

get()

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

Pobiera szczegóły dotyczące 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+

getAll()

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

Pobiera tablicę wszystkich alarmów.

Zwroty

  • Promise<Alarm[]>

    Chrome 91+

Wydarzenia

onAlarm

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

Uruchamia się, gdy upłynie czas alarmu. Przydatne w przypadku stron zdarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak: 

    (alarm: Alarm) => void