browser.alarms

Descrizione

Autorizzazioni

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

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

Concetti e utilizzo

Per garantire un comportamento affidabile, è utile capire come si comporta l'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 vengono attivate. Le sveglie ripetute vengono attivate al massimo una volta e poi vengono 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 l'esecuzione.

Persistenza

Puoi controllare la persistenza di un allarme al momento della creazione utilizzando il flag persistAcrossSessions. 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, è meglio assicurarsi che le sveglie importanti esistano ogni volta che viene avviato il service worker. Ad esempio:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Se la sveglia viene creata in modo dinamico in base all'azione dell'utente, ti consigliamo di memorizzare la creazione della sveglia altrove, in modo da poterla ricreare se necessario.

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

L'esempio seguente imposta una sveglia nel service worker quando viene installata una nuova versione dell'estensione:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

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:

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

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

chrome.alarms.clearAll(): Promise<boolean | undefined>

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

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

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

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