browser.alarms

Descrizione

Utilizza l'API chrome.alarms per pianificare l'esecuzione del codice periodicamente o in un momento specifico nel futuro.

Autorizzazioni

alarms

Per utilizzare l'API browser.alarms, dichiara l'autorizzazione "alarms" nel manifest:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Concetti e utilizzo

Per garantire un comportamento affidabile, è utile capire come si comporta l'API.

Sospensione del dispositivo

Le sveglie continuano a funzionare mentre un dispositivo è in modalità di sospensione. Tuttavia, una sveglia non attiverà un dispositivo. Quando il dispositivo si riattiva, verranno attivati tutti gli allarmi non attivati. Le sveglie ripetute verranno attivate al massimo una volta e poi verranno riprogrammate utilizzando il periodo specificato a partire dal momento in cui il dispositivo si riattiva, senza tenere conto del tempo già trascorso da quando la sveglia è stata impostata per l'esecuzione.

Persistenza

Puoi controllare la persistenza di un allarme al momento della creazione utilizzando il flag persistAcrossSessions. Può essere impostato su true (persiste fino all'aggiornamento dell'estensione) o false (viene cancellato se l'estensione viene ricaricata o il browser si riavvia e ogni volta che l'estensione viene aggiornata).

Altri browser e versioni precedenti di Chrome

Questa proprietà non è supportata in altri browser (problema) o nelle versioni di Chrome precedenti a Chrome 150, dove il comportamento può essere imprevedibile. Di conseguenza, è meglio assicurarsi che gli allarmi importanti esistano ogni volta che il service worker viene avviato. Ad esempio:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Se la sveglia viene creata in modo dinamico in base all'azione dell'utente, ti consigliamo di memorizzare la creazione della sveglia altrove, in modo da sapere se ricrearla, se necessario.

Esempi

I seguenti esempi 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 un'allarme nel service worker quando viene installata una nuova versione dell'estensione:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Rispondi a un allarme

L'esempio seguente imposta l'icona della barra degli strumenti delle azioni in base al nome della sveglia che è scattata.

service-worker.js:

browser.alarms.onAlarm.addListener((alarm) => {
  browser.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Tipi

Alarm

Proprietà

  • nome

    stringa

    Il nome di questa sveglia.

  • periodInMinutes

    number optional

    Se non è null, la sveglia è una sveglia ripetuta e suonerà di nuovo tra periodInMinutes minuti.

  • persistAcrossSessions

    booleano

    Chrome 150+

    Indica se la sveglia deve essere mantenuta tra le sessioni (riavvii del browser).

  • scheduledTime

    numero

    Ora in cui è stata pianificata l'attivazione di questa sveglia, in millisecondi trascorsi dall'epoca (ad es. Date.now() + n). Per motivi di prestazioni, la sveglia potrebbe essere stata ritardata di un periodo di tempo arbitrario oltre questo limite.

AlarmCreateInfo

Proprietà

  • delayInMinutes

    number optional

    Il periodo di tempo in minuti dopo il quale deve essere attivato l'evento onAlarm.

  • nome

    stringa facoltativa

    Chrome 152+

    Il nome di questa sveglia.

  • periodInMinutes

    number optional

    Se impostato, l'evento onAlarm dovrebbe attivarsi ogni periodInMinutes minuti dopo l'evento iniziale specificato da when o delayInMinutes. Se non viene impostato, l'allarme verrà attivato una sola volta.

  • persistAcrossSessions

    boolean facoltativo

    Chrome 150+

    Indica se la sveglia deve essere mantenuta tra le sessioni (riavvii del browser). In Chrome, il valore predefinito è true per corrispondere al comportamento storico, ma devi impostarlo esplicitamente per massimizzare la compatibilità tra i browser.

  • quando

    number optional

    L'ora in cui deve suonare la sveglia, in millisecondi trascorsi dall'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 della sveglia da cancellare. Il valore predefinito è la stringa vuota.

Resi

  • Promise<boolean>

    Chrome 91 e versioni successive

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

Cancella tutte le sveglie.

Resi

  • Promise<boolean | undefined>

    Chrome 91 e versioni successive

create()

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

Crea una sveglia. In prossimità dell'orario o degli orari specificati 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 sul computer dell'utente, Chrome limita gli avvisi a un massimo di una volta al secondo, ma potrebbe ritardarli di un periodo di tempo arbitrario. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 1 secondo non verrà rispettata e genererà un avviso. when può essere impostato su meno di 1 secondo dopo "now" senza avviso, ma non attiverà l'allarme per almeno 1 secondo.

Parametri

  • nome

    stringa facoltativa

    Nome facoltativo per identificare questa sveglia. Il valore predefinito è la stringa vuota.

  • alarmInfo

    AlarmCreateInfo

    Descrive quando deve attivarsi la sveglia. L'ora iniziale deve essere specificata da when o delayInMinutes (ma non da entrambi). Se è impostato periodInMinutes, l'allarme verrà ripetuto ogni periodInMinutes minuti dopo l'evento iniziale. Se non viene impostato né when né delayInMinutes per una sveglia ripetuta, viene utilizzato periodInMinutes come valore predefinito per delayInMinutes.

Resi

  • Promise<void>

    Chrome 111 e versioni successive

    Promise che si risolve quando la sveglia è stata creata.

get()

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

Recupera i dettagli dell'allarme specificato.

Parametri

  • nome

    stringa facoltativa

    Il nome dell'allarme da ottenere. Il valore predefinito è la stringa vuota.

Resi

  • Promise<Alarm | undefined>

    Chrome 91 e versioni successive

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

Restituisce un array di tutte le sveglie.

Resi

  • Promise<Alarm[]>

    Chrome 91 e versioni successive

Eventi

onAlarm

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

Attivato quando una sveglia è scaduta. Utile per le pagine degli eventi.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (alarm: Alarm) => void