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 zostać uruchomione zdarzenie onAlarm.

  • nazwa

    tekst opcjonalny

    Chrome 152+

    Nazwa tego alarmu.

  • periodInMinutes

    liczba opcjonalna

    Jeśli ta opcja jest ustawiona, zdarzenie onAlarm powinno być uruchamiane co periodInMinutes minut po początkowym zdarzeniu określonym przez when lub delayInMinutes. Jeśli ta opcja nie jest ustawiona, alarm zostanie uruchomiony 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 zostać uruchomiony 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 uruchamiane jest 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 zostanie uruchomiony przez co najmniej 30 sekund.

Aby ułatwić Ci 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 zostać uruchomiony 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 powtarzającego się alarmu nie ustawisz wartości when ani delayInMinutes, jako wartość domyślną dla delayInMinutes zostanie użyta wartość periodInMinutes.

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

Uruchamiane, gdy upłynie czas alarmu. Przydatne w przypadku stron zdarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak: 

    (alarm: Alarm) => void