chrome.alarms

Descrizione

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

Autorizzazioni

alarms

Per 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 si attiveranno. 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

Puoi controllare la persistenza di una sveglia 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 viene riavviato 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 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();

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

Esempi

Gli esempi seguenti mostrano come utilizzare e rispondere a una sveglia. Per provare questa API, installa l'esempio di API Alarm dal repository chrome-extension-samples.

Imposta una sveglia

Il seguente esempio imposta una sveglia nel service worker quando viene installata una nuova versione dell'estensione:

service-worker.js:

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

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 periodInMinutes minuti.

  • persistAcrossSessions

    booleano

    In attesa

    Indica 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 importo arbitrario oltre questo.

AlarmCreateInfo

Proprietà

  • delayInMinutes

    number optional

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

  • periodInMinutes

    number optional

    Se impostato, l'evento onAlarm deve essere attivato ogni periodInMinutes minuti dopo l'evento iniziale specificato da when o delayInMinutes. Se non è impostata, la sveglia si attiverà una sola volta.

  • persistAcrossSessions

    booleano facoltativo

    In attesa

    Indica se la sveglia 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 della sveglia da cancellare. 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 verrà visualizzato un avviso. when può essere impostato su un valore inferiore a 30 secondi dopo "ora" senza preavviso, ma non attiverà la sveglia 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 questo allarme. Il valore predefinito è la stringa vuota.

  • alarmInfo

    AlarmCreateInfo

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

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 dell'allarme specificato.

Parametri

  • nome

    stringa facoltativa

    Il nome della sveglia da ottenere. Il valore predefinito è la stringa vuota.

Resi

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

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

Restituisce un array di tutte le sveglie.

Resi

  • Promise<Alarm[]>

    Chrome 91+

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