chrome.alarms

Opis

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

Uprawnienia

alarms

Plik manifestu

Aby używać interfejsu chrome.alarms API, zadeklaruj uprawnienie "alarms" w pliku manifestu:

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

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 po zainstalowaniu rozszerzenia:

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

    tekst

    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

    Chrome 150+

    Czy alarm ma być zachowywany między sesjami (ponownym uruchomieniem 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 mógł zostać opóźniony o dowolną wartość.

AlarmCreateInfo

Właściwości

  • delayInMinutes

    liczba opcjonalna

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

  • nazwa

    tekst opcjonalny

    Oczekuje

    Nazwa tego alarmu.

  • periodInMinutes

    liczba opcjonalna

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

  • persistAcrossSessions

    wartość logiczna opcjonalna

    Chrome 150+

    Czy alarm ma być zachowywany między sesjami (ponownym uruchomieniem przeglądarki). W Chrome domyślnie jest to wartość true, aby zachować zgodność z dotychczasowym działaniem, 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()

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

Usuwa alarm o podanej nazwie.

Parametry

  • nazwa

    tekst opcjonalny

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

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak: 

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome 91+

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach trzeba używać wywołań zwrotnych.

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

Usuwa wszystkie alarmy.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak: 

    (wasCleared: boolean) => void

    • wasCleared

      wartość logiczna

Zwroty

  • Promise<boolean>

    Chrome 91+

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach trzeba używać wywołań zwrotnych.

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): 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 jest ono wczytane w postaci rozpakowanej, nie ma ograniczeń co do częstotliwości uruchamiania alarmu.

Parametry

  • nazwa

    tekst 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. Czas początkowy musi być określony przez when lub delayInMinutes (ale nie oba). Jeśli ustawisz periodInMinutes, alarm będzie się powtarzać co periodInMinutes minut po zdarzeniu początkowym. Jeśli w przypadku alarmu powtarzanego nie ustawisz when ani delayInMinutes, periodInMinutes będzie używane jako domyślna wartość delayInMinutes.

  • callback

    funkcja opcjonalna

    Chrome 111+

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Promise<void>

    Chrome 111+

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

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach trzeba używać wywołań zwrotnych.

get()

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

Pobiera szczegóły określonego alarmu.

Parametry

  • nazwa

    tekst opcjonalny

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

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak: 

    (alarm?: Alarm) => void

    • alarm

      Alarm opcjonalny

Zwroty

  • Promise<Alarm | undefined>

    Chrome 91+

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach trzeba używać wywołań zwrotnych.

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

Pobiera tablicę wszystkich alarmów.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak: 

    (alarms: Alarm[]) => void

Zwroty

  • Promise<Alarm[]>

    Chrome 91+

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach trzeba używać wywołań zwrotnych.

Wydarzenia

onAlarm

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

Uruchamia się, gdy alarm się włączy. Przydatne w przypadku stron zdarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak: 

    (alarm: Alarm) => void