chrome.alarms

Chrome 120: a partire da Chrome 120, l'intervallo minimo di allarme è stato ridotto da 1 minuto a 30 secondi. Affinché una sveglia si attivi tra 30 secondi, imposta periodInMinutes: 0.5.
Chrome 117: a partire da Chrome 117, il numero di sveglie attive è limitato a 500. Una volta raggiunto questo limite, chrome.alarms.create() non riuscirà. Quando utilizzi un callback, viene impostato chrome.runtime.lastError. Quando utilizzi le promesse, queste vengono rifiutate.

Descrizione

Usa l'API chrome.alarms per pianificare l'esecuzione del codice periodicamente o in un orario specifico nel 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 capire il comportamento dell'API.

Sospensione del dispositivo

Le sveglie continuano a essere attive mentre un dispositivo è in sospensione. Tuttavia, una sveglia riattivare un dispositivo. Quando il dispositivo si riattiva, si attivano tutte le sveglie mancate. Le sveglie che si ripetono vengono attivate al massimo una volta e poi riprogrammate utilizzando periodo specificato a partire da quando si riattiva il dispositivo, senza tenere conto qualsiasi tempo trascorso da quando l'allarme era stato inizialmente impostato per essere attivato.

Persistenza

Gli allarmi generalmente rimangono attivi fino all'aggiornamento di un'estensione. Tuttavia, questo non è garantito e gli allarmi potrebbe essere cancellata al riavvio del browser. Di conseguenza, valuta la possibilità di impostare un valore nello spazio di archiviazione. quando viene creata una sveglia, per poi assicurarti 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

I seguenti esempi mostrano come utilizzare e rispondere a un allarme. Per provare questa API, Installa l'esempio dell'API allarme da chrome-extension-samples. repository Git.

Imposta una sveglia

L'esempio seguente imposta 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

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

service-worker.js:

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

Tipi

Alarm

Proprietà

• nome

  stringa

  Nome della sveglia.

• periodInMinutes

  numero facoltativo

  Se il valore non è null, la sveglia è una sveglia ripetuta e si riattiva tra periodInMinutes minuti.

• scheduledTime

  numero

  Ora in cui l'allarme è stato programmato, in millisecondi dopo l'epoca (ad esempio Date.now() + n). Per motivi legati alle prestazioni, l'allarme potrebbe essere stato ritardato di una quantità arbitraria oltre questo valore.

AlarmCreateInfo

Proprietà

• delayInMinutes

  numero facoltativo

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

• periodInMinutes

  numero facoltativo

  Se impostato, l'evento onSimulazione deve essere attivato ogni periodInMinutes minuti dopo l'evento iniziale specificato da when o delayInMinutes. Se non viene impostato, l'allarme si attiverà una sola volta.

• quando

  numero facoltativo

  Ora in cui deve attivarsi l'allarme, in millisecondi dopo l'epoca (ad es. Date.now() + n).

Metodi

clear()

Promesso .

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 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 sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

clearAll()

Promesso .

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

Cancella tutte le sveglie.

Parametri

• callback

  funzione 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 sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

create()

Promesso .

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

Crea una sveglia. In prossimità degli orari specificati da alarmInfo, viene attivato l'evento onAlarm. Se esiste un'altra sveglia con lo stesso nome (o nessun nome se non è specificato), la sveglia verrà annullata e sostituita.

Per ridurre il carico del computer dell'utente, Chrome limita gli allarmi al massimo a una volta ogni 30 secondi, ma potrebbe ritardarli di un importo maggiore in modo arbitrario. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 0.5 non verrà rispettata e comporterà un avviso. when può essere impostato a meno di 30 secondi dopo "ora" senza preavviso, ma non attiverà effettivamente l'allarme per almeno 30 secondi.

Per aiutarti a eseguire il debug dell'app o dell'estensione, una volta caricata l'app o l'estensione non c'è limite alla frequenza di attivazione dell'allarme.

Parametri

• nome

  stringa facoltativo

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

• alarmInfo

  AlarmCreateInfo

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

• callback

  funzione facoltativa

  Chrome 111 e versioni successive .

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promesso<void>

  Chrome 111 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

get()

Promesso .

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

Recupera i dettagli sull'allarme specificato.

Parametri

• nome

  stringa facoltativo

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

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (alarm?: Alarm) => void

  • sveglia

    Sveglia facoltativa

Resi

• Promise&lt;Alarm | non definito>

  Chrome 91 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getAll()

Promesso .

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

Ottiene un array di tutti gli allarmi.

Parametri

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (alarms: Alarm[]) => void

  • sveglie

    Sveglia[]

Resi

• Prometti<sveglia[]>

  Chrome 91 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

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

  • sveglia

    Sveglia