Descrição
Use a API chrome.alarms
para programar a execução periódica 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 o comportamento da API.
Suspensão do dispositivo
Os alarmes continuam em execução enquanto um dispositivo está em suspensão. No entanto, um alarme não acenderá um dispositivo. Quando o dispositivo for ativado, todos os alarmes perdidos serão acionados. Alarmes repetidos serão acionados no máximo uma vez e serão reprogramados usando o período especificado a partir do momento em que o dispositivo for ativado, sem considerar nenhum tempo decorrido desde que o alarme foi definido originalmente para ser executado.
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 for reiniciado. Por isso, considere definir um valor no armazenamento quando um alarme for criado e verifique se ele existe sempre que o service worker é 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 essa API, instale o exemplo da API Alarm (link em inglês) pelo repositório chrome-extension-samples.
Definir 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 de ação na barra de ferramentas com base no nome do alarme que tocou.
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 é recorrente e será disparado novamente em
periodInMinutes
minutos. -
scheduledTime
number
Horário em que o alarme foi programado para disparar, em milissegundos após a época (por exemplo,
Date.now() + n
). Por motivos de desempenho, o alarme pode ter sido adiado por um valor arbitrário além desse.
AlarmCreateInfo
Propriedades
-
delayInMinutes
número opcional
Tempo, em minutos, para disparar o evento
onAlarm
. -
periodInMinutes
número opcional
Se definido, o evento onAlarm vai ser disparado a cada
periodInMinutes
minutos após o evento inicial especificado porwhen
oudelayInMinutes
. Se não for definido, o alarme será disparado apenas uma vez. -
quando
número opcional
Horário em que o alarme deve ser disparado, em milissegundos após a época (por exemplo,
Date.now() + n
).
Métodos
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Limpa o alarme com o nome fornecido.
Parâmetros
-
nome
string opcional
O nome do alarme a ser limpo. O padrão é a string vazia.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Retorna
-
Promise<boolean>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Limpa todos os alarmes.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Retorna
-
Promise<boolean>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
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 alarme.
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 por um período arbitrário mais. Ou seja, definir delayInMinutes
ou periodInMinutes
como menos que 0.5
não será respeitado e causará um alerta. O 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 aplicativo ou extensão, após 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 esse alarme. O padrão é a string vazia.
-
alarmInfo
Descreve quando o alarme deve ser disparado. O tempo inicial precisa ser especificado por
when
oudelayInMinutes
, mas não por ambos. Se aperiodInMinutes
estiver definida, o alarme será repetido a cadaperiodInMinutes
minutos após o evento inicial. Sewhen
oudelayInMinutes
não estiverem definidos para um alarme recorrente,periodInMinutes
será usado como padrão paradelayInMinutes
. -
callback
função optional
Chrome 111 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 111 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Recupera detalhes sobre o alarme especificado.
Parâmetros
Retorna
-
Promise<Alarm | undefined>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Recebe uma matriz de todos os alarmes.
Parâmetros
Retorna
-
Prometer<Alarme[]>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.