Descrizione
Usa l'API chrome.alarms per pianificare l'esecuzione del codice periodicamente o in un orario specifico nel futuro.
Autorizzazioni
alarmsPer utilizzare l'API chrome.alarms, dichiara l'autorizzazione "alarms" nel manifest:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Concetti e utilizzo
Per garantire un comportamento affidabile, è utile capire il comportamento dell'API.
Sospensione del dispositivo
Le sveglie continuano a essere attive mentre un dispositivo è in sospensione. Tuttavia, una sveglia riattivare un dispositivo. Quando il dispositivo si riattiva, si attivano tutte le sveglie mancate. Le sveglie che si ripetono vengono attivate al massimo una volta e poi riprogrammate utilizzando periodo specificato a partire da quando si riattiva il dispositivo, senza tenere conto qualsiasi tempo trascorso da quando l'allarme era stato inizialmente impostato per essere attivato.
Persistenza
Gli allarmi generalmente rimangono attivi fino all'aggiornamento di un'estensione. Tuttavia, questo non è garantito e gli allarmi potrebbe essere cancellata al riavvio del browser. Di conseguenza, valuta la possibilità di impostare un valore nello spazio di archiviazione. quando viene creata una sveglia, per poi assicurarti che esista a ogni avvio del Service worker. Ad esempio:
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();
Esempi
I seguenti esempi mostrano come utilizzare e rispondere a un allarme. Per provare questa API, Installa l'esempio dell'API allarme da chrome-extension-samples. repository Git.
Imposta una sveglia
L'esempio seguente imposta un allarme nel service worker quando viene installata l'estensione:
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
});
});
Rispondere a una sveglia
L'esempio seguente imposta l'icona della barra degli strumenti delle azioni in base al nome della sveglia che si è attivata.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Tipi
Alarm
Proprietà
-
nome
stringa
Nome della sveglia.
-
periodInMinutes
numero facoltativo
Se il valore non è null, la sveglia è una sveglia ripetuta e si riattiva tra
periodInMinutesminuti. -
scheduledTime
numero
Ora in cui l'allarme è stato programmato, in millisecondi dopo l'epoca (ad esempio
Date.now() + n). Per motivi legati alle prestazioni, l'allarme potrebbe essere stato ritardato di una quantità arbitraria oltre questo valore.
AlarmCreateInfo
Proprietà
-
delayInMinutes
numero facoltativo
Periodo di tempo in minuti trascorso il quale deve essere attivato l'evento
onAlarm. -
periodInMinutes
numero facoltativo
Se impostato, l'evento onSimulazione deve essere attivato ogni
periodInMinutesminuti dopo l'evento iniziale specificato dawhenodelayInMinutes. Se non viene impostato, l'allarme si attiverà una sola volta. -
quando
numero facoltativo
Ora in cui deve attivarsi l'allarme, in millisecondi dopo l'epoca (ad es.
Date.now() + n).
Metodi
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Cancella la sveglia con il nome specificato.
Parametri
-
nome
stringa facoltativo
Il nome della sveglia da cancellare. Il valore predefinito è la stringa vuota.
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(wasCleared: boolean) => void
-
wasCleared
booleano
-
Resi
-
Promise<boolean>
Chrome 91 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Cancella tutte le sveglie.
Parametri
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(wasCleared: boolean) => void
-
wasCleared
booleano
-
Resi
-
Promise<boolean>
Chrome 91 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Crea una sveglia. In prossimità degli orari specificati da alarmInfo, viene attivato l'evento onAlarm. Se esiste un'altra sveglia con lo stesso nome (o nessun nome se non è specificato), la sveglia verrà annullata e sostituita.
Per ridurre il carico del computer dell'utente, Chrome limita gli allarmi al massimo a una volta ogni 30 secondi, ma potrebbe ritardarli di un importo maggiore in modo arbitrario. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 0.5 non verrà rispettata e comporterà un avviso. when può essere impostato a meno di 30 secondi dopo "ora" senza preavviso, ma non attiverà effettivamente l'allarme per almeno 30 secondi.
Per aiutarti a eseguire il debug dell'app o dell'estensione, una volta caricata l'app o l'estensione non c'è limite alla frequenza di attivazione dell'allarme.
Parametri
-
nome
stringa facoltativo
Nome facoltativo per identificare la sveglia. Il valore predefinito è la stringa vuota.
-
alarmInfo
Descrive quando deve attivarsi l'allarme. L'ora iniziale deve essere specificata tramite
whenodelayInMinutes(non entrambi). Se il criterioperiodInMinutesè impostato, la sveglia verrà ripetuta ogniperiodInMinutesminuti dopo l'evento iniziale. Se néwhennédelayInMinutesè impostato per una sveglia ricorrente,periodInMinutesviene utilizzato come predefinito perdelayInMinutes. -
callback
funzione facoltativa
Chrome 111 e versioni successive .Il parametro
callbackha il seguente aspetto:() => void
Resi
-
Promesso<void>
Chrome 111 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Recupera i dettagli sull'allarme specificato.
Parametri
Resi
-
Promise<Alarm | non definito>
Chrome 91 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Ottiene un array di tutti gli allarmi.
Parametri
Resi
-
Prometti<sveglia[]>
Chrome 91 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.