Descrizione
Utilizza l'API chrome.alarms per pianificare il codice in modo che venga eseguito periodicamente o in un momento specifico nel futuro.
Autorizzazioni
alarmsPer usare l'API chrome.alarms, dichiara l'autorizzazione "alarms" nel file manifest:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Concetti e utilizzo
Per garantire un comportamento affidabile, è utile comprendere il comportamento dell'API.
Sonno dispositivo
Le sveglie continuano a funzionare mentre un dispositivo è in modalità di sospensione. Tuttavia, una sveglia non riattiva un dispositivo. Quando il dispositivo si attiva, vengono attivate le eventuali sveglie mancate. Le sveglie ripetute si attivano al massimo una volta, quindi vengono riprogrammate utilizzando il periodo specificato a partire da quando il dispositivo si riattiva, senza tenere conto del tempo già trascorso dall'impostazione iniziale della sveglia.
Persistenza
In genere le sveglie rimangono attive fino all'aggiornamento di un'estensione. Tuttavia, questo non è garantito e gli allarmi potrebbero essere cancellati al riavvio del browser. Di conseguenza, valuta la possibilità di impostare un valore nello spazio di archiviazione quando viene creato un allarme, quindi assicurati 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
Gli esempi riportati di seguito mostrano come utilizzare e rispondere a un allarme. Per provare questa API, installa l'esempio dell'API Alarm dal repository chrome-extension-samples.
Impostare una sveglia
Nell'esempio seguente viene impostato 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
Nel seguente esempio viene impostata l'icona della barra degli strumenti delle azioni in base al nome della sveglia attivata.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Tipi
Alarm
Proprietà
-
nome
stringa
Il nome della sveglia.
-
periodInMinutes
numero facoltativo
Se non null, la sveglia è una sveglia ricorrente che si attiverà di nuovo tra
periodInMinutesminuti. -
scheduledTime
numero
L'ora in cui era stata programmata l'attivazione dell'allarme, in millisecondi dopo l'epoca (ad esempio
Date.now() + n). Per motivi legati alle prestazioni, l'allarme potrebbe essere stato ritardato di un importo arbitrario.
AlarmCreateInfo
Proprietà
-
delayInMinutes
numero facoltativo
Periodo di tempo in minuti dopo il quale dovrebbe essere attivato l'evento
onAlarm. -
periodInMinutes
numero facoltativo
Se impostato, l'evento onAlarm dovrebbe attivarsi ogni
periodInMinutesminuti dopo l'evento iniziale specificato dawhenodelayInMinutes. Se non viene configurato, l'allarme si attiverà una sola volta. -
quando
numero facoltativo
L'ora in cui deve essere attivato il rilevatore, in millisecondi successiva all'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
boolean
-
Ritorni
-
Promise<boolean>
Chrome 91 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Consente di cancellare tutte le sveglie.
Parametri
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(wasCleared: boolean)=>void
-
wasCleared
boolean
-
Ritorni
-
Promise<boolean>
Chrome 91 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Crea una sveglia. In prossimità dell'ora o delle ore specificate da alarmInfo, viene attivato l'evento onAlarm. Se esiste un'altra sveglia con lo stesso nome (o senza nome se non è specificato), verrà annullata e sostituita da questa sveglia.
Per ridurre il carico sul computer dell'utente, Chrome limita gli allarmi al massimo una volta ogni 30 secondi, ma potrebbe ritardarli di un importo maggiore. In altre parole, l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 0.5 non verrà rispettata e comporterà un avviso. when può essere impostato su un valore inferiore a 30 secondi dopo "adesso" senza avviso, ma in realtà non attiverà l'allarme per almeno 30 secondi.
Per aiutarti a eseguire il debug della tua app o estensione dopo averla caricata decompressa, non esiste un limite alla frequenza di attivazione dell'allarme.
Parametri
-
nome
stringa facoltativo
Nome facoltativo per identificare questa sveglia. Il valore predefinito è la stringa vuota.
-
alarmInfo
Descrive quando deve attivarsi l'allarme. L'ora iniziale deve essere specificata da
whenodelayInMinutes(ma non da entrambi). Se impostiperiodInMinutes, la sveglia si ripeterà ogniperiodInMinutesminuti dopo l'evento iniziale. Se non è impostato néwhennédelayInMinutesper una sveglia ricorrente, viene utilizzatoperiodInMinutescome impostazione predefinita perdelayInMinutes. -
callback
funzione facoltativa
Chrome 111 e versioni successiveIl parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Chrome 111 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Recupera i dettagli della sveglia specificata.
Parametri
Ritorni
-
Promessa<Sveglia|non definita>
Chrome 91 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Recupera un array di tutte le sveglie.
Parametri
Ritorni
-
Promessa<Sveglia[]>
Chrome 91 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.