browser.alarms

Descrição

Use a API chrome.alarms para programar a execução de código periodicamente ou em um horário específico no futuro.

Permissões

alarms

Para usar a API browser.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 o dispositivo está em repouso. No entanto, um alarme não ativa um dispositivo. Quando o dispositivo for ativado, todos os alarmes perdidos serão disparados. Os alarmes repetidos serão acionados no máximo uma vez e, em seguida, serão reprogramados usando o período especificado a partir do momento em que o dispositivo for ativado, sem considerar o tempo que já passou desde que o alarme foi originalmente definido para ser executado.

Persistência

É possível controlar a persistência de um alarme no momento da criação usando a flag persistAcrossSessions. Isso pode ser definido como true (persiste até que a extensão seja atualizada) ou false (limpo 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 com versões do Chrome anteriores à 150, em que o comportamento pode ser imprevisível. Portanto, é melhor garantir que os alarmes importantes existam sempre que o service worker for iniciado. Exemplo:

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

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

checkAlarmState();

Se o alarme for criado dinamicamente com base na ação do usuário, talvez seja interessante armazenar o fato de que um alarme foi criado em outro lugar para que você saiba que precisa 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:

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

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 acionado.

service-worker.js:

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

Tipos

Alarm

Propriedades

  • nome

    string

    Nome do alarme.

  • periodInMinutes

    número optional

    Se não for nulo, o alarme é recorrente e vai tocar novamente em periodInMinutes minutos.

  • persistAcrossSessions

    booleano

    Chrome 150+

    Se o alarme deve persistir entre as sessões (reinicializações do navegador).

  • scheduledTime

    número

    Horário em que o alarme foi programado para ser acionado, em milissegundos após a época (por exemplo, Date.now() + n). Por motivos de desempenho, o alarme pode ter sido atrasado por um período arbitrário além desse.

AlarmCreateInfo

Propriedades

  • delayInMinutes

    número optional

    Período em minutos após o qual o evento onAlarm deve ser acionado.

  • nome

    string opcional

    Chrome 152+

    Nome do alarme.

  • periodInMinutes

    número optional

    Se definido, o evento onAlarm será acionado a cada periodInMinutes minutos após o evento inicial especificado por when ou delayInMinutes. Se não for definido, o alarme será acionado apenas uma vez.

  • persistAcrossSessions

    booleano opcional

    Chrome 150+

    Se o alarme deve persistir entre as sessões (reinicializações do navegador). No Chrome, o padrão é "true" para corresponder ao comportamento histórico, mas é recomendável definir isso explicitamente para maximizar a compatibilidade entre navegadores.

  • quando

    número optional

    O horário em que o alarme deve ser acionado, em milissegundos após a época (por exemplo, Date.now() + n).

Métodos

clear()

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

Limpa o alarme com o nome informado.

Parâmetros

  • nome

    string opcional

    O nome do alarme a ser apagado. O padrão é a string vazia.

Retorna

  • Promise<boolean>

    Chrome 91+ browser.* desde o Chrome 148

clearAll()

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

Limpa todos os alarmes.

Retorna

  • Promise<boolean | undefined>

    Chrome 91+ browser.* desde o Chrome 148

create()

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

Cria um alarme. Próximo aos horários especificados por alarmInfo, o evento onAlarm é acionado. Se houver outro alarme com o mesmo nome (ou sem nome, se nenhum for especificado), ele será cancelado e substituído por este.

Para reduzir a carga na máquina do usuário, o Chrome limita os alarmes a no máximo uma vez por segundo, mas pode atrasá-los por um período arbitrário. Ou seja, definir delayInMinutes ou periodInMinutes como menos de 1 segundo não será aceito e vai causar um aviso. when pode ser definido para menos de 1 segundo após "agora" sem aviso, mas não vai fazer com que o alarme seja acionado por pelo menos 1 segundo.

Parâmetros

  • nome

    string opcional

    Nome opcional para identificar o alarme. O padrão é a string vazia.

  • alarmInfo

    AlarmCreateInfo

    Descreve quando o alarme deve ser acionado. O horário inicial precisa ser especificado por when ou delayInMinutes (mas não ambos). Se periodInMinutes estiver definido, o alarme será repetido a cada periodInMinutes minutos após o evento inicial. Se nem when nem delayInMinutes estiverem definidos para um alarme repetido, periodInMinutes será usado como padrão para delayInMinutes.

Retorna

  • Promessa<void>

    Chrome 111+ browser.* desde o Chrome 148

    Promessa que é resolvida quando o alarme é criado.

get()

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

Recupera detalhes sobre o alarme especificado.

Parâmetros

  • nome

    string opcional

    O nome do alarme a ser mostrado. O padrão é a string vazia.

Retorna

  • Promise<Alarm | undefined>

    Chrome 91+ browser.* desde o Chrome 148

getAll()

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

Recebe uma matriz de todos os alarmes.

Retorna

  • Promise<Alarm[]>

    Chrome 91+ browser.* desde o Chrome 148

Eventos

onAlarm

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

Acionado quando um alarme é concluído. Útil para páginas de eventos.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (alarm: Alarm) => void