chrome.alarms

refresh date: 2026-09-25 robots: noindex

Descrizione

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

Autorizzazioni

alarms

Manifest

Per utilizzare l'API chrome.alarms, dichiara l'autorizzazione "alarms" nel manifest:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Esempi

I seguenti esempi 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

L'esempio seguente imposta una sveglia nel service worker quando l'estensione viene 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
  });
});

Rispondi a un allarme

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

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 è null, la sveglia è una sveglia ripetuta e suonerà di nuovo tra periodInMinutes minuti.

  • persistAcrossSessions

    booleano

    Chrome 150+

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

  • scheduledTime

    numero

    Ora in cui è stata pianificata l'attivazione di questa sveglia, in millisecondi trascorsi dall'epoca (ad es. Date.now() + n). Per motivi di prestazioni, la sveglia potrebbe essere stata ritardata di un periodo di tempo arbitrario oltre questo limite.

AlarmCreateInfo

Proprietà

  • delayInMinutes

    number optional

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

  • nome

    stringa facoltativa

    Chrome 152+

    Il nome di questa sveglia.

  • periodInMinutes

    number optional

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

  • persistAcrossSessions

    boolean facoltativo

    Chrome 150+

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

  • quando

    number optional

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

Metodi

clear()

Promise 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): 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.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (wasCleared: boolean) => void

    • wasCleared

      booleano

Resi

  • Promise<boolean>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean | undefined>

Cancella tutte le sveglie.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (wasCleared?: boolean) => void

    • wasCleared

      boolean facoltativo

Resi

  • Promise<boolean | undefined>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

Crea una sveglia. In prossimità dell'orario o degli orari specificati 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 sul computer dell'utente, Chrome limita gli avvisi a un massimo di una volta al secondo, ma potrebbe ritardarli di un periodo di tempo arbitrario. Ciò significa che l'impostazione di delayInMinutes o periodInMinutes su un valore inferiore a 1 secondo non verrà rispettata e genererà un avviso. when può essere impostato su meno di 1 secondo dopo "now" senza avviso, ma non attiverà l'allarme per almeno 1 secondo.

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 da entrambi). Se è impostato periodInMinutes, l'allarme verrà ripetuto ogni periodInMinutes minuti dopo l'evento iniziale. Se non viene impostato né when né delayInMinutes per una sveglia ripetuta, viene utilizzato periodInMinutes come valore predefinito per delayInMinutes.

  • callback

    funzione elemento facoltativo

    Chrome 111 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 111 e versioni successive

    Promise che si risolve quando la sveglia è stata creata.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

get()

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

Recupera i dettagli dell'allarme specificato.

Parametri

  • nome

    stringa facoltativa

    Il nome dell'allarme da ottenere. Il valore predefinito è la stringa vuota.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (alarm?: Alarm) => void

    • sveglia

      Alarm facoltativo

Resi

  • Promise<Alarm | undefined>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

Restituisce un array di tutte le sveglie.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (alarms: Alarm[]) => void

Resi

  • Promise<Alarm[]>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i 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