Descrição
Use a API chrome.alarms para programar a execução de código periodicamente ou em um horário especificado no futuro.
Permissões
alarmsManifesto
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 do repositório chrome-extension-samples.
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 foi disparado.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Tipos
Alarm
Propriedades
-
nome
string
É o nome desse alarme.
-
periodInMinutes
número optional
Se não for nulo, o alarme será repetido e disparado novamente em
periodInMinutesminutos. -
persistAcrossSessions
booleano
Chrome 150+Indica se o alarme deve persistir entre sessões (reinicializações do navegador).
-
scheduledTime
número
O 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 sido atrasado por um período arbitrário além disso.
AlarmCreateInfo
Propriedades
-
delayInMinutes
número optional
Período de tempo em minutos após o qual o evento
onAlarmdeve ser disparado. -
periodInMinutes
número optional
Se definido, o evento onAlarm será disparado a cada
periodInMinutesminutos após o evento inicial especificado porwhenoudelayInMinutes. Se não estiver definido, o alarme será disparado apenas uma vez. -
persistAcrossSessions
booleano optional
Chrome 150+Indica se o alarme deve persistir entre sessões (reinicializações do navegador). No Chrome, o padrão é "true" para corresponder ao comportamento histórico, mas você precisa definir isso explicitamente para maximizar a compatibilidade entre navegadores.
-
quando
número optional
O horário em que o alarme deve disparar, em milissegundos após a época (por exemplo,
Date.now() + n).
Métodos
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
): Promise<boolean>
Limpa o alarme com o nome informado.
Parâmetros
-
nome
string optional
O nome do alarme a ser limpo. O padrão é a string vazia.
-
callback
função optional
O parâmetro
callbacktem 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()
chrome.alarms.clearAll(
callback?: function,
): Promise<boolean>
Limpa todos os alarmes.
Parâmetros
-
callback
função optional
O parâmetro
callbacktem 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()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
): Promise<void>
Cria um alarme. Próximo ao horário especificado por alarmInfo, o evento onAlarm é disparado. Se houver outro alarme com o mesmo nome (ou nenhum nome, se nenhum for especificado), ele será cancelado e substituído por esse 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. Ou seja, definir delayInMinutes ou periodInMinutes como menor que 0.5 não será aceito e causará um aviso. when pode ser definido como menos de 30 segundos após "agora" sem aviso, mas não fará com que o alarme seja disparado por pelo menos 30 segundos.
Para ajudar a depurar seu app ou extensão, quando você o carrega descompactado, não há limite para a frequência com que o alarme pode ser disparado.
Parâmetros
-
nome
string optional
Nome opcional para identificar esse alarme. O padrão é a string vazia.
-
alarmInfo
Descreve quando o alarme deve disparar. O horário inicial precisa ser especificado por
whenoudelayInMinutes(mas não ambos). SeperiodInMinutesestiver definido, o alarme será repetido a cadaperiodInMinutesminutos após o evento inicial. SewhenoudelayInMinutesnão estiverem definidos para um alarme repetido,periodInMinutesserá usado como padrão paradelayInMinutes. -
callback
função optional
Chrome 111+O parâmetro
callbacktem esta aparência:() => void
Retorna
-
Promessa<void>
Chrome 111+Promessa que é resolvida quando o alarme é criado.
As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
get()
chrome.alarms.get(
name?: string,
callback?: function,
): Promise<Alarm | undefined>
Recupera detalhes sobre o alarme especificado.
Parâmetros
Retorna
-
Promessa<Alarme | indefinido>
Chrome 91+As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getAll()
chrome.alarms.getAll(
callback?: function,
): Promise<Alarm[]>
Recebe uma matriz de todos os alarmes.
Parâmetros
Retorna
-
Promessa<Alarme[]>
Chrome 91+As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.