Descrizione
Utilizza l'API chrome.alarms per pianificare l'esecuzione del codice periodicamente o in un momento specifico in 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 comprendere il funzionamento dell'API.
Sospensione del dispositivo
Le sveglie continuano a funzionare mentre un dispositivo è in modalità Sospensione. Tuttavia, una sveglia non riattiva un dispositivo. Quando il dispositivo si riattiva, le sveglie perse vengono attivate. Le sveglie ripetute si attiveranno al massimo una volta e verranno riprogrammate utilizzando il periodo specificato a partire dal momento in cui il dispositivo si riattiva, senza tenere conto del tempo trascorso dall'impostazione originale della sveglia.
Persistenza
In genere, gli allarmi persistono fino all'aggiornamento di un'estensione. Tuttavia, questa operazione non è garantita e le sveglie potrebbero essere cancellate al riavvio del browser. Di conseguenza, assicurati che esista ogni volta che viene avviato il service worker. Ad esempio:
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
Esempi
Gli esempi seguenti mostrano come utilizzare e rispondere a un allarme. Per provare questa API, installa l'esempio di API Alarm dal repository chrome-extension-samples.
Imposta una sveglia
L'esempio seguente imposta una sveglia nel service worker quando l'estensione viene installata:
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 un allarme
L'esempio seguente imposta l'icona della barra degli strumenti delle azioni in base al nome dell'allarme che è scattato.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Tipi
Alarm
Proprietà
-
nome
stringa
Il nome di questa sveglia.
-
periodInMinutes
number optional
Se non è nullo, la sveglia è ripetuta e si attiverà di nuovo tra
periodInMinutesminuti. -
persistAcrossSessions
booleano
In attesaIndica se l'allarme deve persistere tra le sessioni (riavvii del browser).
-
scheduledTime
numero
Ora in cui è stata pianificata l'attivazione di questo allarme, in millisecondi trascorsi dall'epoca (ad es.
Date.now() + n). Per motivi di prestazioni, l'allarme potrebbe essere stato ritardato di un intervallo di tempo arbitrario.
AlarmCreateInfo
Proprietà
-
delayInMinutes
number optional
Durata in minuti dopo la quale deve essere attivato l'evento
onAlarm. -
periodInMinutes
number optional
Se impostato, l'evento onAlarm deve essere attivato ogni
periodInMinutesminuti dopo l'evento iniziale specificato dawhenodelayInMinutes. Se non è impostata, la sveglia si attiverà una sola volta. -
persistAcrossSessions
booleano facoltativo
In attesaIndica se l'allarme deve persistere tra le sessioni (riavvii del browser). In Chrome, questa impostazione è impostata su true per impostazione predefinita in modo da corrispondere al comportamento storico, ma devi impostarla in modo esplicito per massimizzare la compatibilità tra i browser.
-
quando
number optional
Ora in cui deve essere attivato l'allarme, in millisecondi dopo l'epoca (ad es.
Date.now() + n).
Metodi
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
Cancella la sveglia con il nome specificato.
Parametri
-
nome
stringa facoltativa
Il nome dell'allarme da disattivare. Il valore predefinito è la stringa vuota.
Resi
-
Promise<boolean>
Chrome 91+
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
Cancella tutte le sveglie.
Resi
-
Promise<boolean>
Chrome 91+
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
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 ne è stato specificato uno), verrà annullata e sostituita da questa sveglia.
Per ridurre il carico sulla macchina dell'utente, Chrome limita gli allarmi a un massimo di una volta ogni 30 secondi, ma può ritardarli di un ulteriore periodo di tempo arbitrario. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 0.5 non verrà rispettata e causerà un avviso. when può essere impostato su un valore inferiore a 30 secondi dopo "ora" senza avvisi, ma l'allarme non si attiverà per almeno 30 secondi.
Per aiutarti a eseguire il debug dell'app o dell'estensione, una volta caricata non pacchettizzata, non esiste un limite alla frequenza con cui può attivarsi l'allarme.
Parametri
-
nome
stringa facoltativa
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 entrambi). SeperiodInMinutesè impostato, l'allarme si ripeterà ogniperiodInMinutesminuti dopo l'evento iniziale. Se non è impostato néwhennédelayInMinutesper una sveglia ripetuta,periodInMinutesviene utilizzato come valore predefinito perdelayInMinutes.
Resi
-
Promise<void>
Chrome 111+Promessa che viene risolta quando viene creata la sveglia.
get()
chrome.alarms.get(
name?: string,
): Promise<Alarm | undefined>
Recupera i dettagli della sveglia specificata.
Parametri
-
nome
stringa facoltativa
Il nome dell'allarme da ottenere. Il valore predefinito è la stringa vuota.
Resi
-
Promise<Alarm | undefined>
Chrome 91+
Resi
-
Promise<Alarm[]>
Chrome 91+