chrome.alarms

Chrome 120:a partir do Chrome 120, o intervalo mínimo de alarme foi reduzido de 1 minuto para 30 segundos. Para que um alarme seja acionado em 30 segundos, defina periodInMinutes: 0.5.
Chrome 117:a partir do Chrome 117, o número de alarmes ativos é limitado a 500. Quando esse limite for atingido, o chrome.alarms.create() vai falhar. Ao usar um callback, chrome.runtime.lastError será definido. Ao usar promessas, elas serão recusadas.

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

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 a ser executados enquanto o dispositivo está em suspensão. No entanto, um alarme não ativar um dispositivo. Quando o dispositivo for ativado, todos os alarmes perdidos serão disparados. Alarmes repetidos serão acionados no máximo uma vez e serão reprogramados usando o período especificado a partir da ativação do dispositivo, sem considerar qualquer período decorrido desde que o alarme foi originalmente definido para execução.

Persistência

Os alarmes geralmente persistem até que uma extensão seja atualizada. No entanto, isso não é garantido, e os alarmes podem ser apagados quando o navegador é reiniciado. Por isso, defina um valor no armazenamento quando um alarme é criado e verifique se ele existe toda vez que o service worker for iniciado. Exemplo:

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

Exemplos

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

Definir um alarme

O exemplo a seguir define um alarme no service worker quando a extensão está 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ções 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 deste alarme.

• periodInMinutes

  número opcional

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

• scheduledTime

  number

  Horário em que esse alarme foi programado para disparar, em milissegundos após a época (por exemplo, Date.now() + n). Por motivos de desempenho, o alarme pode ter um atraso arbitrário além disso.

AlarmCreateInfo

Propriedades

• delayInMinutes

  número opcional

  Período em minutos para que o evento onAlarm seja disparado.

• periodInMinutes

  número opcional

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

• quando

  número opcional

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

Métodos

clear()

Promessa

chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Apaga o alarme com o nome fornecido.

Parâmetros

• nome

  string opcional

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

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (wasCleared: boolean) => void

  • wasCleared

    booleano

Retorna

• Promise<boolean>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

clearAll()

Promessa

chrome.alarms.clearAll(
  callback?: function,
)

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 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

create()

Promessa

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Cria um alarme. Perto dos horários especificados por alarmInfo, o evento onAlarm é disparado. Se houver outro alarme com o mesmo nome (ou sem nome, se nenhum for especificado), ele será cancelado e substituído por esse alarme.

Para reduzir a carga no computador do usuário, o Chrome limita os alarmes a no máximo uma vez a cada 30 segundos, mas pode atrasá-los um pouco mais. Ou seja, definir delayInMinutes ou periodInMinutes como menor que 0.5 não será considerado e vai causar um aviso. when pode ser definido para menos de 30 segundos após "agora" sem aviso, mas não faz com que o alarme dispare por pelo menos 30 segundos.

Para ajudar você a depurar seu app ou extensão, depois de carregá-lo descompactado, não há limite para a frequência com que o alarme pode ser disparado.

Parâmetros

• nome

  string opcional

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

• alarmInfo

  AlarmCreateInfo

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

• callback

  função opcional

  Chrome 111 ou versões mais recentes

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 111 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

get()

Promessa

chrome.alarms.get(
  name?: string,
  callback?: function,
)

Recupera detalhes sobre o alarme especificado.

Parâmetros

• nome

  string opcional

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

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (alarm?: Alarm) => void

  • alarme

    Alarme opcional

Retorna

• Promise&lt;Alarm | indefinido>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAll()

Promessa

chrome.alarms.getAll(
  callback?: function,
)

Recebe uma matriz de todos os alarmes.

Parâmetros

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (alarms: Alarm[]) => void

  • alarmes

    Alarme[]

Retorna

• Promessa<Alarme[]>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onAlarm

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

Disparado quando um alarme atinge a duração. Útil para páginas de eventos.

Parâmetros

• callback

  função

  O parâmetro callback tem esta aparência:

  (alarm: Alarm) => void

  • alarme

    Alarme