chroom.alarmen

Beschrijving

Gebruik de chrome.alarms API om te plannen dat code periodiek of op een bepaald tijdstip in de toekomst wordt uitgevoerd.

Machtigingen

alarms

Om de chrome.alarms API te gebruiken, declareert u de toestemming "alarms" in het manifest : 

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

Concepten en gebruik

Om betrouwbaar gedrag te garanderen, is het nuttig om te begrijpen hoe de API zich gedraagt.

Apparaat slaap

Alarmen blijven actief terwijl een apparaat slaapt. Een alarm zal een apparaat echter niet wekken. Wanneer het apparaat wakker wordt, worden eventuele gemiste alarmen geactiveerd. Herhaalde alarmen worden maximaal één keer geactiveerd en vervolgens opnieuw gepland volgens de opgegeven periode, te rekenen vanaf het moment dat het apparaat ontwaakt, waarbij geen rekening wordt gehouden met de tijd die al is verstreken sinds het alarm oorspronkelijk was ingesteld.

Vasthoudendheid

Alarmen blijven doorgaans bestaan ​​totdat een extensie wordt bijgewerkt. Dit is echter niet gegarandeerd en alarmen kunnen worden gewist wanneer de browser opnieuw wordt opgestart. Overweeg daarom om een ​​waarde in de opslag in te stellen wanneer er een alarm wordt gegenereerd, en zorg er vervolgens voor dat deze waarde elke keer bestaat als uw servicemedewerker opstart. Bijvoorbeeld: 

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

Voorbeelden

De volgende voorbeelden laten zien hoe u een alarm kunt gebruiken en erop kunt reageren. Om deze API te proberen, installeert u het Alarm API-voorbeeld uit de chrome-extension-samples- repository.

Zet een wekker

In het volgende voorbeeld wordt een alarm ingesteld bij de servicemedewerker wanneer de extensie wordt geïnstalleerd:

service-werker.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
  });
});

Reageer op een alarm

In het volgende voorbeeld wordt het actiewerkbalkpictogram ingesteld op basis van de naam van het alarm dat is afgegaan.

service-werker.js: 

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

Soorten

Alarm

Eigenschappen

  • naam

    snaar

    Naam van dit alarm.

  • periodeInMinuten

    nummer optioneel

    Als het alarm niet nul is, is het een herhalend alarm en wordt het binnen periodInMinutes minuten opnieuw geactiveerd.

  • geplande tijd

    nummer

    Tijd waarop dit alarm volgens planning zou afgaan, in milliseconden na het tijdperk (bijvoorbeeld Date.now() + n ). Om prestatieredenen kan het alarm een ​​willekeurige hoeveelheid vertraging hebben opgelopen.

AlarmCreateInfo

Eigenschappen

  • vertragingInMinuten

    nummer optioneel

    Tijdsduur in minuten waarna de onAlarm gebeurtenis moet worden geactiveerd.

  • periodeInMinuten

    nummer optioneel

    Indien ingesteld, moet de onAlarm-gebeurtenis elke periodInMinutes minuten na de eerste gebeurtenis worden geactiveerd die is opgegeven door when of delayInMinutes . Indien niet ingesteld, zal het alarm slechts één keer afgaan.

  • wanneer

    nummer optioneel

    Tijd waarop het alarm moet afgaan, in milliseconden voorbij het tijdperk (bijvoorbeeld Date.now() + n ).

Methoden

clear()

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

Wist het alarm met de opgegeven naam.

Parameters

  • naam

    tekenreeks optioneel

    De naam van het alarm dat moet worden gewist. Standaard ingesteld op de lege tekenreeks.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (wasCleared: boolean) => void

    • werd gewist

      Booleaans

Retouren

  • Beloof<boolean>

    Chroom 91+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

clearAll()

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

Wist alle alarmen.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (wasCleared: boolean) => void

    • werd gewist

      Booleaans

Retouren

  • Beloof<boolean>

    Chroom 91+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

create()

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

Creëert een alarm. Tegen de tijd(en) gespecificeerd door alarmInfo wordt de gebeurtenis onAlarm geactiveerd. Als er nog een alarm is met dezelfde naam (of geen naam als er geen is opgegeven), wordt dit geannuleerd en vervangen door dit alarm.

Om de belasting van de machine van de gebruiker te verminderen, beperkt Chrome alarmen tot maximaal één keer per 30 seconden, maar kan deze nog een willekeurige hoeveelheid langer worden uitgesteld. Dat wil zeggen dat het instellen van delayInMinutes of periodInMinutes op minder dan 0.5 niet wordt gehonoreerd en een waarschuwing zal veroorzaken. when kan worden ingesteld op minder dan 30 seconden na "nu" zonder waarschuwing, maar zal er niet voor zorgen dat het alarm gedurende ten minste 30 seconden afgaat.

Om u te helpen bij het opsporen van fouten in uw app of extensie, geldt er geen limiet voor hoe vaak het alarm kan afgaan als u deze uitgepakt heeft geladen.

Parameters

  • naam

    tekenreeks optioneel

    Optionele naam om dit alarm te identificeren. Standaard ingesteld op de lege tekenreeks.

  • Beschrijft wanneer het alarm moet afgaan. De initiële tijd moet worden opgegeven door when of delayInMinutes (maar niet door beide). Als periodInMinutes is ingesteld, wordt het alarm iedere periodInMinutes minuten na de eerste gebeurtenis herhaald. Als noch when noch delayInMinutes is ingesteld voor een herhalend alarm, wordt periodInMinutes als standaard gebruikt voor delayInMinutes .

  • terugbellen

    functie optioneel

    Chroom 111+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 111+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

get()

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

Haalt details op over het opgegeven alarm.

Parameters

  • naam

    tekenreeks optioneel

    De naam van het alarm dat moet worden opgehaald. Standaard ingesteld op de lege tekenreeks.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (alarm?: Alarm) => void

Retouren

  • Belofte< Alarm | ongedefinieerd>

    Chroom 91+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getAll()

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

Krijgt een array van alle alarmen.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (alarms: Alarm[]) => void

Retouren

  • Beloof < Alarm []>

    Chroom 91+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

Evenementen

onAlarm

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

Wordt geactiveerd wanneer een alarm is verstreken. Handig voor evenementenpagina's.

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

    (alarm: Alarm) => void