chrome.alarms

Descrição

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

Permissões

alarms

Manifesto

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

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

Exemplos

Os exemplos a seguir mostram como usar e responder a um alarme. Para testar essa API, instale o exemplo da API Alarm no repositório chrome-extension-samples (link em inglês).

Definir um alarme

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

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

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

service-worker.js:

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

Tipos

Alarm

Propriedades

  • nome

    string

    Nome do alarme.

  • periodInMinutes

    number optional

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

  • scheduledTime

    número

    Hora em que o disparo do alarme foi programado, em milissegundos após a época (por exemplo, Date.now() + n). Por motivos de desempenho, o alarme pode ter sido atrasado em uma quantidade arbitrária além disso.

AlarmCreateInfo

Propriedades

  • delayInMinutes

    number optional

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

  • periodInMinutes

    number optional

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

  • quando

    number optional

    O momento em que o alarme deve disparar, em milissegundos após o período (por exemplo, Date.now() + n).

Métodos

clear()

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

Limpa o alarme com o nome especificado.

Parâmetros

  • nome

    string opcional

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (wasCleared: boolean) => void

    • wasCleared

      booleano

Retorna

  • Promise<boolean>

    Chrome 91+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

clearAll()

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

Limpa todos os alarmes.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (wasCleared: boolean) => void

    • wasCleared

      booleano

Retorna

  • Promise<boolean>

    Chrome 91+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

create()

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

Cria um alarme. Perto dos 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 a cada 30 segundos, mas pode atrasá-los em uma quantidade arbitrária. Ou seja, definir delayInMinutes ou periodInMinutes como um valor menor que 0.5 não será aceito e vai gerar um aviso. when pode ser definido para menos de 30 segundos após "agora" sem aviso, mas não vai disparar o alarme por pelo menos 30 segundos.

Para ajudar você a depurar seu app ou extensão, quando ele é carregado descompactado, não há limite para a frequência com que o alarme pode ser acionado.

Parâmetros

  • nome

    string opcional

    Nome opcional para identificar o alarme. O padrão é uma 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 vai se repetir a cada periodInMinutes minutos após o evento inicial. Se nem when nem delayInMinutes estiverem definidos para um alarme recorrente, periodInMinutes será usado como padrão para delayInMinutes.

  • callback

    função opcional

    Chrome 111 ou mais recente

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

get()

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

Recupera detalhes sobre o alarme especificado.

Parâmetros

  • nome

    string opcional

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (alarm?: Alarm) => void

Retorna

  • Promise<Alarm | undefined>

    Chrome 91+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAll()

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

Recebe uma matriz de todos os alarmes.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (alarms: Alarm[]) => void

Retorna

  • Promise<Alarm[]>

    Chrome 91+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onAlarm

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

Disparado quando um alarme expira. Útil para páginas de eventos.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (alarm: Alarm) => void