Opis
Za pomocą interfejsu API chrome.alarms
możesz zaplanować uruchamianie kodu okresowo lub o określonej godzinie w przyszłości.
Uprawnienia
alarms
Plik manifestu
Aby korzystać z 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ć 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 przezwhen
lubdelayInMinutes
. 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()
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 wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
clearAll()
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 wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
create()
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
Określa, kiedy ma się uruchomić alarm. Początkowy czas musi być określony za pomocą funkcji
when
lubdelayInMinutes
(ale nie obu jednocześnie). Jeśli ustawiona jest wartośćperiodInMinutes
, alarm będzie powtarzany coperiodInMinutes
min po pierwszym zdarzeniu. Jeśli dla powtarzanego alarmu nie ustawiono żadnej funkcjiwhen
anidelayInMinutes
, domyślną wartością dla funkcjidelayInMinutes
jestperiodInMinutes
. -
wywołanie zwrotne
funkcja opcjonalnie
Chrome 111 i nowsze wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 111 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Pobiera szczegóły określonego alarmu.
Parametry
Zwroty
-
Promise<Alarm | undefined>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Pobiera tablicę wszystkich alarmów.
Parametry
Zwroty
-
Obietnica<Alarm[]>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.