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 comportamento dell'API.

Sospensione del dispositivo

Le sveglie continuano a funzionare mentre un dispositivo è in modalità Sospensione. Tuttavia, una sveglia non risveglierà un dispositivo. Quando il dispositivo si riattiva, vengono attivate le sveglie perse. Le sveglie ripetute vengono attivate al massimo una volta e poi vengono riprogrammate utilizzando il periodo specificato a partire dall'accensione del dispositivo, senza tenere conto del tempo già trascorso dall'attivazione originale della sveglia.

Persistenza

In genere, gli allarmi rimangono attivi fino all'aggiornamento di un'estensione. Tuttavia, non è garantito e le sveglie potrebbero essere cancellate al riavvio del browser. Di conseguenza, ti consigliamo di impostare un valore nello spazio di archiviazione quando viene creato un avviso e di assicurarti che esista ogni volta che viene avviato il tuo worker di servizio. 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 una sveglia. 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 è 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 si è attivato.

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 facoltativo

    Se non è nullo, la sveglia è ripetuta e verrà attivata di nuovo tra periodInMinutes minuti.

  • scheduledTime

    numero

    Ora in cui è stato pianificato l'avvio di questo avviso, in millisecondi dopo l'epoca (ad es. Date.now() + n). Per motivi di prestazioni, l'avviso potrebbe essere stato ritardato di un periodo arbitrario oltre questo.

AlarmCreateInfo

Proprietà

  • delayInMinutes

    number facoltativo

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

  • periodInMinutes

    number facoltativo

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

  • quando

    number facoltativo

    Ora in cui deve essere attivata l'allerta, in millisecondi dopo l'epoca (ad es. Date.now() + n).

Metodi

clear()

Promessa 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Cancella la sveglia con il nome specificato.

Parametri

  • nome

    stringa facoltativa

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

  • callback

    function facoltativa

    Il parametro callback ha 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 i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

clearAll()

Promessa 
chrome.alarms.clearAll(
  callback?: function,
)

Cancella tutte le sveglie.

Parametri

  • callback

    function facoltativa

    Il parametro callback ha 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 i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

create()

Promessa 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Crea una sveglia. Vicino alle 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 nessuno), verrà annullata e sostituita da questa sveglia.

Per ridurre il carico sulla macchina dell'utente, Chrome limita le sveglie a un massimo di una ogni 30 secondi, ma può ritardarle per un periodo di tempo arbitrario. In altre parole, 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 meno di 30 secondi dopo "ora" senza avviso, ma non attiverà effettivamente la sveglia per almeno 30 secondi.

Per aiutarti a eseguire il debug dell'app o dell'estensione, una volta caricata non esiste alcun limite alla frequenza con cui può essere attivata la sveglia.

Parametri

  • nome

    stringa facoltativa

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

  • alarmInfo

    AlarmCreateInfo

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

  • callback

    function facoltativa

    Chrome 111 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 111 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

get()

Promessa 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Recupera i dettagli della sveglia specificata.

Parametri

  • nome

    stringa facoltativa

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

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (alarm?: Alarm) => void

Resi

  • Promise<Alarm | undefined>

    Chrome 91 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getAll()

Promessa 
chrome.alarms.getAll(
  callback?: function,
)

Restituisce un array di tutte le sveglie.

Parametri

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (alarms: Alarm[]) => void

Resi

  • Promise<Alarm[]>

    Chrome 91 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onAlarm

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

Viene attivato quando è trascorso il tempo impostato per una sveglia. Utile per le pagine degli eventi.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (alarm: Alarm) => void