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

In genere, gli allarmi rimangono attivi 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

Il seguente esempio imposta una sveglia 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 un allarme

L'esempio seguente imposta l'icona della barra degli strumenti delle azioni in base al nome dell'allarme 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 optional

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

  • 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 periodo 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 periodInMinutes minuti dopo l'evento iniziale specificato da when o delayInMinutes. Se non è impostato, l'allarme si attiverà una sola volta.

  • quando

    number optional

    Ora in cui deve scattare 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 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 causerà un avviso. when può essere impostato su un valore inferiore a 30 secondi dopo "ora" senza avviso, ma non attiverà l'allarme per almeno 30 secondi.

Per aiutarti a eseguire il debug dell'app o dell'estensione, una volta caricata decompressa, 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

    AlarmCreateInfo

    Descrive quando deve attivarsi la sveglia. 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+

get()

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

Recupera i dettagli della sveglia specificata.

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