chrome.alarms

Opis

Użyj interfejsu chrome.alarms API, aby zaplanować uruchamianie kodu okresowo lub 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 na niego reagować. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Alarm API z repozytorium chrome-extension-samples.

Ustaw alarm

W tym przykładzie alarm jest ustawiany w procesie 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

W tym przykładzie ikona paska narzędzi działania jest ustawiana 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

    number opcjonalny

    Jeśli nie jest to wartość null, alarm jest powtarzany i włączy się ponownie za periodInMinutes minut.

  • scheduledTime

    liczba

    Czas, w którym alarm miał się włączyć, 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

    number opcjonalny

    Czas w minutach, po którym powinno zostać wywołane zdarzenie onAlarm.

  • periodInMinutes

    number opcjonalny

    Jeśli ta wartość jest ustawiona, zdarzenie onAlarm powinno być wywoływane co periodInMinutes minut po początkowym zdarzeniu określonym przez when lub delayInMinutes. Jeśli nie zostanie ustawiony, alarm uruchomi się tylko raz.

  • kiedy

    number opcjonalny

    Czas, w którym ma się włączyć alarm, w milisekundach od początku epoki (np. Date.now() + n).

Metody

clear()

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

Usuwa alarm o podanej nazwie.

Parametry

  • nazwa

    string opcjonalny

    Nazwa alarmu do wyczyszczenia. 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 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

clearAll()

Obietnica 
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 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

create()

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

Tworzy alarm. W okolicach czasu określonego przez alarmInfo wywoływane 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 urządzenia użytkownika, Chrome ogranicza liczbę alarmów do maksymalnie 1 na 30 sekund, ale może je opóźnić o dowolną wartość. Oznacza to, że ustawienie wartości delayInMinutes lub periodInMinutes mniejszej niż 0.5 nie zostanie uwzględnione i spowoduje wyświetlenie ostrzeżenia. when można ustawić na czas krótszy niż 30 sekund od „teraz” bez ostrzeżenia, ale alarm nie zostanie włączony przez co najmniej 30 sekund.

Aby ułatwić Ci debugowanie aplikacji lub rozszerzenia, po załadowaniu go w formie rozpakowanej nie ma ograniczeń co do częstotliwości wywoływania alarmu.

Parametry

  • nazwa

    string opcjonalny

    Opcjonalna nazwa identyfikująca ten alarm. Domyślnie jest to pusty ciąg znaków.

  • alarmInfo

    AlarmCreateInfo

    Opisuje, kiedy ma się włączyć alarm. Czas początkowy musi być określony przez when lub delayInMinutes (ale nie oba). Jeśli ustawisz wartość periodInMinutes, alarm będzie się powtarzać co periodInMinutes minut po pierwszym zdarzeniu. Jeśli w przypadku powtarzającego się alarmu nie ustawiono wartości when ani delayInMinutes, domyślną wartością delayInMinutes jest periodInMinutes.

  • callback

    funkcja opcjonalna

    Chrome 111 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 111 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

get()

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

Pobiera szczegóły określonego alarmu.

Parametry

  • nazwa

    string 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 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getAll()

Obietnica 
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 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onAlarm

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

Uruchamiane po upływie czasu alarmu. Przydatne w przypadku stron wydarzeń.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (alarm: Alarm) => void