Behandel evenementen met servicemedewerkers

Handleiding die concepten van medewerkers in de voorlichtingsdienst behandelt

Overzicht

Deze handleiding biedt een introductie tot Chrome Extension Service Workers. In deze handleiding bouw je een extensie waarmee gebruikers snel naar referentiepagina's van de Chrome API kunnen navigeren via de adresbalk. Je leert hoe je:

• Registreer uw servicemedewerker en importeer modules.
• Debug uw extensieserviceworker.
• Beheer de status en verwerk gebeurtenissen.
• Periodieke gebeurtenissen activeren.
• Communiceer met behulp van contentscripts.

Voordat je begint

Deze handleiding gaat ervan uit dat u basiskennis van webontwikkeling hebt. We raden u aan om Extensions 101 en Hello World te bekijken voor een introductie tot het ontwikkelen van extensies.

Bouw de extensie

Begin met het aanmaken van een nieuwe map genaamd quick-api-reference om de extensiebestanden in op te slaan, of download de broncode van onze GitHub-voorbeeldenrepository .

Stap 1: Registreer de dienstverlener

Maak het manifestbestand aan in de hoofdmap van het project en voeg de volgende code toe:

manifest.json:

{
  "manifest_version": 3,
  "name": "Open extension API reference",
  "version": "1.0.0",
  "icons": {
    "16": "images/icon-16.png",
    "128": "images/icon-128.png"
  },
  "background": {
    "service_worker": "service-worker.js"
  }
}

Extensies registreren hun service worker in het manifest, dat slechts één JavaScript-bestand accepteert. Het is niet nodig om navigator.serviceWorker.register() aan te roepen, zoals je dat in een webpagina zou doen.

Maak een map met images aan en download de pictogrammen daarin.

Bekijk de eerste stappen van de handleiding 'Leestijd' voor meer informatie over de metadata en pictogrammen van de extensie in het manifest.

Stap 2: Importeer meerdere service worker-modules

Onze service worker implementeert twee functionaliteiten. Voor een betere onderhoudbaarheid implementeren we elke functionaliteit in een aparte module. Eerst moeten we de service worker declareren als een Elasticsearch-module in ons manifest, zodat we modules in onze service worker kunnen importeren:

manifest.json:

{
 "background": {
    "service_worker": "service-worker.js",
    "type": "module"
  },
}

Maak het bestand service-worker.js aan en importeer twee modules:

import './sw-omnibox.js';
import './sw-tips.js';

Maak deze bestanden aan en voeg aan elk bestand een consolelog toe.

console.log("sw-omnibox.js");

console.log("sw-tips.js");

Zie Scripts importeren voor meer informatie over andere manieren om meerdere bestanden in een service worker te importeren.

Optioneel: Debuggen van de service worker

Ik zal uitleggen hoe je de service worker-logs kunt vinden en kunt zien wanneer deze is beëindigd. Volg eerst de instructies voor het laden van een uitgepakte extensie .

Na 30 seconden ziet u 'service worker (inactief)', wat betekent dat de service worker is beëindigd. Klik op de link 'service worker (inactief)' om deze te inspecteren. De volgende animatie laat dit zien.

Merkte je dat de service worker werd geactiveerd toen je deze inspecteerde? Door de service worker in de ontwikkelaarstools te openen, blijft deze actief. Om ervoor te zorgen dat je extensie correct blijft werken wanneer de service worker wordt beëindigd, vergeet dan niet de ontwikkelaarstools te sluiten.

Nu kun je de extensie uitschakelen om te achterhalen waar de fouten zich bevinden. Een manier om dit te doen is door ".js" te verwijderen uit de import van './sw-omnibox.js' in het bestand service-worker.js . Chrome kan de service worker dan niet meer registreren.

Ga terug naar chrome://extensions en vernieuw de extensie. Je ziet dan twee foutmeldingen:

Service worker registration failed. Status code: 3.

An unknown error occurred when fetching the script.

Zie 'Extensies debuggen' voor meer manieren om de service worker van de extensie te debuggen.

Stap 4: Initialiseer de toestand

Chrome schakelt service workers uit als ze niet nodig zijn. We gebruiken de chrome.storage API om de status te behouden tussen service worker-sessies. Voor toegang tot de opslag moeten we toestemming vragen in het manifest:

manifest.json:

{
  ...
  "permissions": ["storage"],
}

Sla eerst de standaardsuggesties op in de opslag. We kunnen de status initialiseren wanneer de extensie voor het eerst wordt geïnstalleerd door te luisteren naar de runtime.onInstalled() gebeurtenis:

sw-omnibox.js:

...
// Save default API suggestions
chrome.runtime.onInstalled.addListener(({ reason }) => {
  if (reason === 'install') {
    chrome.storage.local.set({
      apiSuggestions: ['tabs', 'storage', 'scripting']
    });
  }
});

Service workers hebben geen directe toegang tot het window-object en kunnen daarom geen gebruik maken van window.localStorage om waarden op te slaan. Bovendien zijn service workers kortstondige uitvoeringsomgevingen; ze worden herhaaldelijk beëindigd tijdens een browsersessie, waardoor ze niet compatibel zijn met globale variabelen. Gebruik in plaats daarvan chrome.storage.local dat gegevens op de lokale machine opslaat.

Zie 'Gegevens opslaan in plaats van globale variabelen gebruiken' voor meer informatie over andere opslagopties voor extension service workers.

Stap 5: Registreer uw evenementen

Alle eventlisteners moeten statisch worden geregistreerd in de globale scope van de service worker. Met andere woorden, eventlisteners mogen niet genesteld zijn in asynchrone functies. Op deze manier kan Chrome ervoor zorgen dat alle eventhandlers worden hersteld in geval van een herstart van de service worker.

In dit voorbeeld gaan we de chrome.omnibox API gebruiken, maar eerst moeten we de omnibox-keywordtrigger in het manifest declareren:

manifest.json:

{
  ...
  "minimum_chrome_version": "102",
  "omnibox": {
    "keyword": "api"
  },
}

Registreer nu de omnibox-gebeurtenislisteners op het hoogste niveau van het script. Wanneer de gebruiker het omnibox-trefwoord ( api ) in de adresbalk invoert, gevolgd door een tabtoets of spatie, zal Chrome een lijst met suggesties weergeven op basis van de opgeslagen trefwoorden. De onInputChanged() -gebeurtenis, die de huidige gebruikersinvoer en een suggestResult object als argumenten ontvangt, is verantwoordelijk voor het vullen van deze suggesties.

sw-omnibox.js:

...
const URL_CHROME_EXTENSIONS_DOC =
  'https://developer.chrome.com/docs/extensions/reference/';
const NUMBER_OF_PREVIOUS_SEARCHES = 4;

// Display the suggestions after user starts typing
chrome.omnibox.onInputChanged.addListener(async (input, suggest) => {
  await chrome.omnibox.setDefaultSuggestion({
    description: 'Enter a Chrome API or choose from past searches'
  });
  const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
  const suggestions = apiSuggestions.map((api) => {
    return { content: api, description: `Open chrome.${api} API` };
  });
  suggest(suggestions);
});

Nadat de gebruiker een suggestie heeft geselecteerd, opent onInputEntered() de bijbehorende Chrome API-referentiepagina.

sw-omnibox.js:

...
// Open the reference page of the chosen API
chrome.omnibox.onInputEntered.addListener((input) => {
  chrome.tabs.create({ url: URL_CHROME_EXTENSIONS_DOC + input });
  // Save the latest keyword
  updateHistory(input);
});

De functie updateHistory() neemt de invoer van de omnibox en slaat deze op in storage.local . Op deze manier kan de meest recente zoekterm later als suggestie in de omnibox worden gebruikt.

sw-omnibox.js:

...
async function updateHistory(input) {
  const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
  apiSuggestions.unshift(input);
  apiSuggestions.splice(NUMBER_OF_PREVIOUS_SEARCHES);
  return chrome.storage.local.set({ apiSuggestions });
}

Stap 6: Stel een terugkerende gebeurtenis in

De methoden setTimeout() of setInterval() worden vaak gebruikt om taken met vertraging of periodieke taken uit te voeren. Deze API's kunnen echter falen omdat de scheduler de timers annuleert wanneer de service worker wordt beëindigd. In plaats daarvan kunnen extensies de chrome.alarms API gebruiken.

Begin met het aanvragen van de "alarms" -toestemming in het manifest:

manifest.json:

{
  ...
  "permissions": ["storage"],
  "permissions": ["storage", "alarms"],
}

De extensie haalt alle tips op, kiest er willekeurig één uit en slaat deze op. We maken een alarm aan dat één keer per dag afgaat om de tip bij te werken. Alarmen worden niet opgeslagen wanneer je Chrome sluit. We moeten dus controleren of het alarm bestaat en het aanmaken als dat niet het geval is.

sw-tips.js:

// Fetch tip & save in storage
const updateTip = async () => {
  const response = await fetch('https://chrome.dev/f/extension_tips/');
  const tips = await response.json();
  const randomIndex = Math.floor(Math.random() * tips.length);
  return chrome.storage.local.set({ tip: tips[randomIndex] });
};

const ALARM_NAME = 'tip';

// Check if alarm exists to avoid resetting the timer.
// The alarm might be removed when the browser session restarts.
async function createAlarm() {
  const alarm = await chrome.alarms.get(ALARM_NAME);
  if (typeof alarm === 'undefined') {
    chrome.alarms.create(ALARM_NAME, {
      delayInMinutes: 1,
      periodInMinutes: 1440
    });
    updateTip();
  }
}

createAlarm();

// Update tip once a day
chrome.alarms.onAlarm.addListener(updateTip);

Stap 7: Communiceer met andere contexten

Extensies gebruiken contentscripts om de inhoud van de pagina te lezen en te wijzigen. Wanneer een gebruiker een referentiepagina van de Chrome API bezoekt, werkt het contentscript van de extensie de pagina bij met de tip van de dag. Het stuurt een bericht naar de service worker om de tip van de dag op te vragen.

Begin met het declareren van het content-script in het manifest en voeg het match-patroon toe dat overeenkomt met de documentatie van de Chrome API .

manifest.json:

{
  ...
  "content_scripts": [
    {
      "matches": ["https://developer.chrome.com/docs/extensions/reference/*"],
      "js": ["content.js"]
    }
  ]
}

Maak een nieuw contentbestand aan. De volgende code stuurt een bericht naar de service worker met het verzoek om de tip. Vervolgens wordt een knop toegevoegd die een pop-upvenster opent met de tip over de extensie. Deze code maakt gebruik van de nieuwe Popover API van het webplatform.

content.js:

(async () => {
  // Sends a message to the service worker and receives a tip in response
  const { tip } = await chrome.runtime.sendMessage({ greeting: 'tip' });

  const nav = document.querySelector('.upper-tabs > nav');
  
  const tipWidget = createDomElement(`
    <button type="button" popovertarget="tip-popover" popovertargetaction="show" style="padding: 0 12px; height: 36px;">
      <span style="display: block; font: var(--devsite-link-font,500 14px/20px var(--devsite-primary-font-family));">Tip</span>
    </button>
  `);

  const popover = createDomElement(
    `<div id='tip-popover' popover style="margin: auto;">${tip}</div>`
  );

  document.body.append(popover);
  nav.append(tipWidget);
})();

function createDomElement(html) {
  const dom = new DOMParser().parseFromString(html, 'text/html');
  return dom.body.firstElementChild;
}

De laatste stap is het toevoegen van een berichtafhandelaar aan onze service worker die een antwoord met de dagelijkse tip naar het contentscript stuurt.

sw-tips.js:

...
// Send tip to content script via messaging
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.greeting === 'tip') {
    chrome.storage.local.get('tip').then(sendResponse);
    return true;
  }
});

Test of het werkt

Controleer of de bestandsstructuur van uw project er als volgt uitziet:

Laad uw extensie lokaal.

Om een ​​uitgepakte extensie in de ontwikkelaarsmodus te laden, volg je de stappen in "Hallo wereld" .

Een referentiepagina openen

1. Voer het trefwoord "api" in de adresbalk van uw browser in.
2. Druk op "tab" of "spatie".
3. Voer de volledige naam van de API in.
   • Of kies uit een lijst met eerdere zoekopdrachten.
4. Er wordt een nieuwe pagina geopend met de referentiepagina van de Chrome API.

Het zou er zo uit moeten zien:

Open de tip van de dag

Klik op de knop 'Tip' in de navigatiebalk om de extensietip te openen.

🎯 Mogelijke verbeteringen

Probeer op basis van wat je vandaag hebt geleerd een van de volgende dingen te doen:

• Onderzoek een andere manier om de suggesties in de omnibox te implementeren.
• Maak je eigen aangepaste modale venster om de extensietip weer te geven.
• Open een extra pagina in de referentie-API-pagina's van MDN voor webextensies.

Blijf bouwen!

Gefeliciteerd met het afronden van deze tutorial 🎉. Blijf je vaardigheden verbeteren door andere tutorials voor beginners te volgen:

Ga verder met verkennen

Om je leertraject als medewerker van de voorlichtingsdienst voort te zetten, raden we je aan de volgende artikelen te raadplegen:

• Over medewerkers van de voorlichtingsdienst .
• De levenscyclus van een medewerker van een extensieservice .
• Evenementen voor dienstverlenende werknemers