chrome.alarms

Descrição

Permissões

Para usar a API chrome.alarms, declare a permissão "alarms" no manifesto:

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

Conceitos e uso

Para garantir um comportamento confiável, é útil entender como a API se comporta.

Suspensão do dispositivo

Os alarmes continuam sendo executados enquanto um dispositivo está suspenso. No entanto, um alarme não vai ativar um dispositivo. Quando o dispositivo é ativado, todos os alarmes perdidos são disparados. Os alarmes repetidos são disparados no máximo uma vez e, em seguida, são reprogramados usando o período especificado a partir do momento em que o dispositivo é ativado, sem considerar o tempo que já passou desde que o alarme foi originalmente definido para execução.

Persistência

É possível controlar a persistência de um alarme no momento da criação usando a persistAcrossSessions flag. Ela pode ser definida como true (persiste até que a extensão seja atualizada) ou false (limpa se a extensão for recarregada ou o navegador for reiniciado e sempre que a extensão for atualizada).

Outros navegadores e versões anteriores do Chrome

Essa propriedade não é compatível com outros navegadores (problema) ou em versões do Chrome anteriores à 150, em que o comportamento pode ser imprevisível. Consequentemente, é melhor garantir que alarmes importantes existam sempre que o service worker for iniciado. Exemplo:

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

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

checkAlarmState();

Se o alarme for criado dinamicamente com base na ação do usuário, talvez seja necessário armazenar que um alarme foi criado em outro lugar para que você saiba como recriá-lo, se necessário.

Exemplos

Os exemplos a seguir mostram como usar e responder a um alarme. Para testar essa API, instale o exemplo da API Alarm do repositório chrome-extension-samples.

Definir um alarme

O exemplo a seguir define um alarme no service worker quando uma nova versão da extensão é instalada:

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
  });
});

Responder a um alarme

O exemplo a seguir define o ícone da barra de ferramentas de ação com base no nome do alarme que foi disparado.

service-worker.js:

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

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

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

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,
)