chrome.alarms

Descrizione

Utilizza l'API chrome.alarms per pianificare l'esecuzione periodica del codice o a un'ora specificata 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 suonare mentre un dispositivo è in sospensione. Tuttavia, una sveglia non riattiva un dispositivo. Quando il dispositivo si riattiva, suonano tutte le sveglie perse. Le sveglie ripetute suoneranno 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 da quando la sveglia è stata originariamente impostata per suonare.

Persistenza

Puoi controllare la persistenza di una sveglia al momento della creazione utilizzando il persistAcrossSessions flag. 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, è consigliabile assicurarsi che le sveglie 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, potresti voler memorizzare che è stata creata una sveglia altrove in modo da sapere di ricrearla, se necessario.

Esempi

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

Imposta una sveglia

L'esempio seguente 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
  });
});

Rispondi a una sveglia

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

service-worker.js:

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

Tipi

Alarm

Proprietà

  • name

    stringa

    Il nome di questa sveglia.

  • periodInMinutes

    numero facoltativo

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

  • persistAcrossSessions

    booleano

    Chrome 150+

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

  • scheduledTime

    numero

    L'ora in cui è stata programmata la sveglia, in millisecondi dall'epoca (ad es. Date.now() + n). Per motivi di prestazioni, la sveglia potrebbe essere stata ritardata di una quantità arbitraria oltre questo valore.

AlarmCreateInfo

Proprietà

  • delayInMinutes

    numero facoltativo

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

  • periodInMinutes

    numero facoltativo

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

  • persistAcrossSessions

    booleano facoltativo

    Chrome 150+

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

  • when

    numero facoltativo

    L'ora in cui deve suonare la sveglia, in millisecondi dall'epoca (ad es. Date.now() + n).

Metodi

clear()

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

Cancella la sveglia con il nome specificato.

Parametri

  • name

    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. All'ora o 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 viene specificato uno), verrà annullata e sostituita da questa sveglia.

Per ridurre il carico sul computer dell'utente, Chrome limita le sveglie a una volta ogni 30 secondi, ma potrebbe ritardarle di una quantità arbitraria in più. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 0.5 non verrà rispettata e genererà un avviso. when può essere impostato su un valore inferiore a 30 secondi dopo "ora" senza avviso, ma la sveglia non suonerà per almeno 30 secondi.

Per aiutarti a eseguire il debug dell'app o dell'estensione, quando l'hai caricata non pacchettizzata, non esiste un limite alla frequenza con cui l'allarme può attivarsi.

Parametri

  • name

    stringa facoltativa

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

  • alarmInfo

    AlarmCreateInfo

    Descrive quando deve suonare la sveglia. L'ora iniziale deve essere specificata da when o delayInMinutes (ma non da entrambi). Se periodInMinutes è impostato, la sveglia 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 si risolve quando la sveglia è stata creata.

get()

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

Recupera i dettagli della sveglia specificata.

Parametri

  • name

    stringa facoltativa

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

Resi

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

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

Recupera un array di tutte le sveglie.

Resi

  • Promise<Alarm[]>

    Chrome 91+

Eventi

onAlarm

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

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

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (alarm: Alarm) => void