chrome.alarms

Opis

Za pomocą interfejsu API chrome.alarms możesz zaplanować uruchamianie kodu okresowo lub o określonej godzinie 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 interfejsu API, warto poznać jego działanie.

Uśpienie urządzenia

Alarmy będą nadal działać, gdy urządzenie jest uśpione. Alarm jednak nie wybudza urządzenia. Po wybudzeniu urządzenia wszystkie pominięte alarmy uruchomią się. Powtarzające się alarmy uruchomią się najwyżej raz, a potem zostaną przełożone na ustawiony okres od chwili wybudzenia urządzenia, bez uwzględniania czasu, który upłynął od uruchomienia alarmu.

Trwałość

Alarmy zazwyczaj są aktywne do czasu aktualizacji rozszerzenia. Nie jest to jednak gwarantowane i alarmy mogą zostać usunięte po ponownym uruchomieniu przeglądarki. Dlatego rozważ ustawienie wartości w pamięci po utworzeniu alarmu i upewnij się, że jest ona obecna przy każdym uruchomieniu skryptu service 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ć alarmów i reagować na nie. Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs Alarm API z repozytorium chrome-extension-samples.

Ustaw alarm

Ten przykład pokazuje alarm w skrypcie service worker, gdy rozszerzenie jest zainstalowane:

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

Poniższy przykład pokazuje, jak ustawić ikonę na pasku narzędzi działań na podstawie nazwy alarmu.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Typy

Alarm

Właściwości

  • nazwa

    string,

    Nazwa tego alarmu.

  • periodInMinutes

    Liczba opcjonalnie

    Jeśli nie ma wartości null, alarm jest powtarzany i uruchomi się ponownie za periodInMinutes minuty.

  • scheduledTime

    Liczba

    Czas uruchomienia tego alarmu (w milisekundach po jego dacie), np. Date.now() + n. Ze względu na wydajność alarm mógł się opóźnić o dowolną wartość.

AlarmCreateInfo

Właściwości

  • delayInMinutes

    Liczba opcjonalnie

    Długość czasu (w minutach), po którym powinno być uruchamiane zdarzenie onAlarm.

  • periodInMinutes

    Liczba opcjonalnie

    Jeśli jest ustawione, zdarzenie onAlarm powinno być uruchamiane co periodInMinutes min po pierwszym zdarzeniu określonym przez when lub delayInMinutes. Jeśli jej nie skonfigurujesz, alarm uruchomi się tylko raz.

  • gdzie

    Liczba opcjonalnie

    Godzina uruchomienia alarmu (w milisekundach od początku epoki, np. Date.now() + n).

Metody

clear()

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

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.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Zwroty

  • Promise<boolean>

    Chrome 91 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

clearAll()

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

Usuwa wszystkie alarmy.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Zwroty

  • Promise<boolean>

    Chrome 91 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

create()

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

Tworzy alarm. Zdarzenie onAlarm jest uruchamiane w okolicach godzin określonych przez zasadę alarmInfo. Jeśli istnieje inny alarm o tej samej nazwie (lub jeśli nie podasz żadnej nazwy), zostanie on anulowany i zastąpiony tym alarmem.

Aby zmniejszyć obciążenie komputera użytkownika, Chrome ogranicza alarmy do nie częściej niż co 30 sekund, ale może dodatkowo opóźniać alarm. Oznacza to, że ustawienie delayInMinutes lub periodInMinutes na wartość mniejszą niż 0.5 nie będzie uwzględniane i spowoduje wyświetlenie ostrzeżenia. Ustawienie when można ustawić na mniej niż 30 sekund po „teraz” bez ostrzeżenia, ale nie spowoduje uruchomienia alarmu przez co najmniej 30 sekund.

Aby ułatwić debugowanie aplikacji lub rozszerzenia, po rozpakowaniu aplikacji 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 się uruchomić alarm. Początkowy czas musi być określony za pomocą funkcji when lub delayInMinutes (ale nie obu jednocześnie). Jeśli ustawiona jest wartość periodInMinutes, alarm będzie powtarzany co periodInMinutes min po pierwszym zdarzeniu. Jeśli dla powtarzanego alarmu nie ustawiono żadnej funkcji when ani delayInMinutes, domyślną wartością dla funkcji delayInMinutes jest periodInMinutes.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 111 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Zwroty

  • Promise<void>

    Chrome 111 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

get()

Obietnica 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Pobiera szczegóły określonego alarmu.

Parametry

  • nazwa

    ciąg znaków opcjonalny

    Nazwa alarmu, który chcesz otrzymać. Domyślnie jest to pusty ciąg znaków.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (alarm?: Alarm)=>void

    • alarm

      Alarm opcjonalny

Zwroty

  • Obietnica<alarm|undefined>

    Chrome 91 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAll()

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

Pobiera tablicę wszystkich alarmów.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (alarms: Alarm[])=>void

Zwroty

  • Obietnica<Alarm[]>

    Chrome 91 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onAlarm

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

Uruchamiane po zakończeniu alarmu. Ta opcja jest przydatna na stronach wydarzeń.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (alarm: Alarm)=>void