Arbeitsbereich-Fenster

Das workbox-window-Paket besteht aus einer Reihe von Modulen, die im window-Kontext ausgeführt werden sollen, also innerhalb Ihrer Webseiten. Sie sind eine Ergänzung zu den anderen Workbox-Paketen, die im Service Worker ausgeführt werden.

Die wichtigsten Funktionen/Ziele von workbox-window sind:

• Um die Registrierung und Aktualisierung von Service Workern zu vereinfachen, indem Entwickler die kritischsten Momente im Service Worker-Lebenszyklus erkennen und besser darauf reagieren können
• So wird verhindert, dass Entwickler häufige Fehler machen.
• Um eine einfachere Kommunikation zwischen dem im Service Worker ausgeführten Code und dem im Fenster ausgeführten Code zu ermöglichen.

workbox-window importieren und verwenden

Der primäre Einstiegspunkt für das workbox-window-Paket ist die Klasse Workbox. Sie können sie entweder aus unserem CDN oder mithilfe eines der gängigen JavaScript-Bündelungstools in Ihren Code importieren.

CDN verwenden

Am einfachsten kannst du die Workbox-Klasse auf deiner Website aus unserem CDN importieren:

<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    wb.register();
  }
</script>

In diesem Beispiel werden <script type="module"> und die import-Anweisung verwendet, um die Klasse Workbox zu laden. Auch wenn Sie denken, dass Sie diesen Code transpilieren müssen, damit er in älteren Browsern funktioniert, ist das eigentlich nicht erforderlich.

Alle gängigen Browser, die Service-Worker unterstützen, unterstützen auch native JavaScript-Module. Es ist also absolut in Ordnung, diesen Code in beliebigen Browsern bereitzustellen. Ältere Browser ignorieren ihn.

Workbox mit JavaScript-Bundlern laden

Für die Verwendung von workbox-window sind keine Tools erforderlich. Wenn Ihre Entwicklungsinfrastruktur aber bereits einen Bundler wie webpack oder Rollup enthält, der mit npm-Abhängigkeiten funktioniert, können Sie damit workbox-window laden.

Der erste Schritt besteht darin, workbox-window als Abhängigkeit Ihrer Anwendung zu installieren:

npm install workbox-window

Verwenden Sie dann in einer der JavaScript-Dateien Ihrer Anwendung die Arbeitsbox import, indem Sie auf den Paketnamen workbox-window verweisen:

import {Workbox} from 'workbox-window';

if ('serviceWorker' in navigator) {
  const wb = new Workbox('/sw.js');

  wb.register();
}

Wenn Ihr Bundler die Codeaufteilung über dynamische Importanweisungen unterstützt, können Sie workbox-window auch bedingt laden. Dadurch sollte die Größe des Haupt-Bundles Ihrer Seite reduziert werden.

Auch wenn workbox-window relativ klein ist, gibt es keinen Grund, warum es mit der Kernanwendungslogik der Website geladen werden muss, da Service Worker von Natur aus eine progressive Verbesserung sind.

if ('serviceWorker' in navigator) {
  const {Workbox} = await import('workbox-window');

  const wb = new Workbox('/sw.js');
  wb.register();
}

Erweiterte Bündelungskonzepte

Im Gegensatz zu den Workbox-Paketen, die im Service Worker ausgeführt werden, werden die Build-Dateien, auf die in den Feldern main und module von workbox-window in package.json verwiesen wird, in ES5 transpiliert. Dadurch sind sie mit den heutigen Build-Tools kompatibel, von denen einige es Entwicklern nicht ermöglichen, ihre node_module-Abhängigkeiten zu transpilieren.

Wenn Sie mit Ihrem Build-System die Abhängigkeiten transpilieren oder keinen Code transpilieren müssen, ist es besser, eine bestimmte Quelldatei anstelle des Pakets selbst zu importieren.

Im Folgenden werden die verschiedenen Möglichkeiten zum Importieren von Workbox zusammen mit einer Erklärung der jeweiligen Ergebnisse aufgeführt:

// Imports a UMD version with ES5 syntax
// (pkg.main: "build/workbox-window.prod.umd.js")
const {Workbox} = require('workbox-window');

// Imports the module version with ES5 syntax
// (pkg.module: "build/workbox-window.prod.es5.mjs")
import {Workbox} from 'workbox-window';

// Imports the module source file with ES2015+ syntax
import {Workbox} from 'workbox-window/Workbox.mjs';

Beispiele

Nachdem Sie die Workbox-Klasse importiert haben, können Sie sie verwenden, um sich zu registrieren und mit Ihrem Service Worker zu interagieren. Hier sind einige Beispiele dafür, wie Sie Workbox in Ihrer Anwendung verwenden können:

Registrieren Sie einen Service Worker und benachrichtigen Sie den Nutzer, wenn dieser Service Worker zum ersten Mal aktiv ist

Viele Webanwendungen nutzen Service Worker, um Assets vorab im Cache zu speichern, damit ihre Anwendung beim nachfolgenden Laden der Seite offline funktioniert. In manchen Fällen kann es sinnvoll sein, den Nutzer darüber zu informieren, dass die App jetzt offline verfügbar ist.

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // `event.isUpdate` will be true if another version of the service
  // worker was controlling the page when this version was registered.
  if (!event.isUpdate) {
    console.log('Service worker activated for the first time!');

    // If your service worker is configured to precache assets, those
    // assets should all be available now.
  }
});

// Register the service worker after event listeners have been added.
wb.register();

Nutzer benachrichtigen, wenn ein Service Worker installiert hat, aber auf die Aktivierung wartet

Wenn eine von einem vorhandenen Service Worker kontrollierte Seite einen neuen Service Worker registriert, wird dieser Service Worker standardmäßig erst aktiviert, wenn alle vom ursprünglichen Service Worker gesteuerten Clients vollständig entladen wurden.

Dies kann bei Entwicklern zu Verwirrung führen, insbesondere in Fällen, in denen das Aktualisieren der aktuellen Seite nicht zur Aktivierung des neuen Service Workers führt.

Die Klasse Workbox bietet ein waiting-Ereignis, auf das Sie warten können, um Verwechslungen zu vermeiden und klarzustellen, wann das der Fall ist:

const wb = new Workbox('/sw.js');

wb.addEventListener('waiting', event => {
  console.log(
    `A new service worker has installed, but it can't activate` +
      `until all tabs running the current version have fully unloaded.`
  );
});

// Register the service worker after event listeners have been added.
wb.register();

Benachrichtigen Sie den Nutzer über Cache-Updates aus dem workbox-broadcast-update-Paket

Das workbox-broadcast-update-Paket ist eine gute Möglichkeit, Inhalte aus dem Cache für eine schnelle Bereitstellung bereitzustellen und gleichzeitig den Nutzer mithilfe der Strategie „Veraltet“ über Aktualisierungen dieser Inhalte zu informieren.

Um diese Aktualisierungen aus dem Fenster zu erhalten, können Sie message-Ereignisse vom Typ CACHE_UPDATED überwachen:

const wb = new Workbox('/sw.js');

wb.addEventListener('message', event => {
  if (event.data.type === 'CACHE_UPDATED') {
    const {updatedURL} = event.data.payload;

    console.log(`A newer version of ${updatedURL} is available!`);
  }
});

// Register the service worker after event listeners have been added.
wb.register();

Dem Service Worker eine Liste der im Cache zu speichernden URLs senden

Bei einigen Anwendungen ist es möglich, alle Assets zu kennen, die während der Build-Erstellung vorab im Cache gespeichert werden müssen. Einige Anwendungen stellen jedoch ganz andere Seiten bereit, je nachdem, auf welche URL der Nutzer zuerst gelangt.

Bei Apps in dieser Kategorie kann es sinnvoll sein, nur die Assets im Cache zu speichern, die der Nutzer für die jeweilige besuchte Seite benötigt hat. Wenn Sie das Paket workbox-routing verwenden, können Sie Ihrem Router eine Liste von URLs senden, die im Cache gespeichert werden sollen. Diese URLs werden dann gemäß den für den Router selbst definierten Regeln im Cache gespeichert.

In diesem Beispiel wird bei jeder Aktivierung eines neuen Service Workers eine Liste von URLs, die von der Seite geladen werden, an den Router gesendet. Es ist kein Problem, alle URLs zu senden, da nur die URLs im Cache gespeichert werden, die einer im Service Worker definierten Route entsprechen:

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // Get the current page URL + all resources the page loaded.
  const urlsToCache = [
    location.href,
    ...performance.getEntriesByType('resource').map(r => r.name),
  ];
  // Send that list of URLs to your router in the service worker.
  wb.messageSW({
    type: 'CACHE_URLS',
    payload: {urlsToCache},
  });
});

// Register the service worker after event listeners have been added.
wb.register();

Wichtige Momente im Service Worker-Lebenszyklus

Der Service-Worker-Lebenszyklus ist komplex und kann schwierig zu verstehen sein. Es ist unter anderem so komplex, dass es alle Grenzfälle für alle möglichen Nutzungen von Service Workern verarbeiten muss (z.B. das Registrieren mehrerer Service Worker, das Registrieren verschiedener Service Worker in verschiedenen Frames, das Registrieren von Service Workern mit unterschiedlichen Namen usw.).

Die meisten Entwickler, die Service Worker implementieren, müssen sich jedoch nicht um all diese Grenzfälle kümmern, da ihre Verwendung recht einfach ist. Die meisten Entwickler registrieren nur einen Service Worker pro Seitenaufbau und ändern nicht den Namen der Service Worker-Datei, die sie auf ihrem Server bereitstellen.

Die Klasse Workbox bietet eine vereinfachte Ansicht für den Service Worker-Lebenszyklus, indem alle Service Worker-Registrierungen in zwei Kategorien unterteilt werden: den eigenen registrierten Service Worker der Instanz und einen externen Service Worker:

• Registrierter Service Worker: ein Service Worker, der mit der Installation begonnen hat, weil die Workbox-Instanz register() aufgerufen hat oder der bereits aktive Service Worker, wenn durch den Aufruf von register() kein updatefound-Ereignis bei der Registrierung ausgelöst wurde.
• Externer Service Worker: ein Service Worker, der unabhängig von der Instanz Workbox mit der Installation begonnen hat, die register() aufruft. Dies geschieht in der Regel, wenn ein Nutzer eine neue Version Ihrer Website in einem anderen Tab geöffnet hat. Wenn das Ereignis von einem externen Service Worker stammt, wird das Attribut isExternal des Ereignisses auf true gesetzt.

Im Folgenden finden Sie eine Übersicht aller wichtigen Momente im Service Worker-Lebenszyklus sowie Empfehlungen für Entwickler zu deren Handhabung:

Die erste Installation eines Service Workers

Die erste Installation durch einen Service Worker sollte anders behandelt werden als alle zukünftigen Updates.

In workbox-window können Sie zwischen der ersten Installation und zukünftigen Updates der Version unterscheiden. Dazu prüfen Sie bei einem der folgenden Ereignisse das Attribut isUpdate. Bei der ersten Installation ist isUpdate false.

const wb = new Workbox('/sw.js');

wb.addEventListener('installed', event => {
  if (!event.isUpdate) {
    // First-installed code goes here...
  }
});

wb.register();

Wenn eine aktualisierte Version des Service Workers gefunden wird

Wenn die Installation eines neuen Service Workers beginnt, die Seite jedoch derzeit von einer vorhandenen Version gesteuert wird, ist das Attribut isUpdate aller folgenden Ereignisse true.

Wie Sie in dieser Situation reagieren, unterscheidet sich in der Regel von der ersten Installation, da Sie festlegen müssen, wann und wie die Nutzer dieses Update erhalten.

Wenn eine unerwartete Version des Service Workers gefunden wird

Manchmal lassen Nutzer Ihre Website sehr lange in einem Tab im Hintergrund geöffnet. Vielleicht öffnen sie sogar einen neuen Tab und navigieren zu Ihrer Website, ohne zu bemerken, dass sie Ihre Website bereits in einem Tab im Hintergrund geöffnet hat. In solchen Fällen besteht die Möglichkeit, dass zwei Versionen deiner Website gleichzeitig ausgeführt werden. Das kann für dich als Entwickler einige interessante Probleme mit sich bringen.

Stellen Sie sich ein Szenario vor, in dem auf Tab A v1 Ihrer Website und auf Tab B v2 ausgeführt wird. Wenn Tab B geladen wird, wird er von der Version Ihres Service Workers gesteuert, der mit v1 geliefert wurde. Die vom Server zurückgegebene Seite enthält jedoch alle V2-Assets (bei Verwendung einer netzwerkorientierten Caching-Strategie für Ihre Navigationsanfragen).

Dies ist jedoch im Allgemeinen kein Problem für Tab B, da Sie beim Schreiben Ihres V2-Codes bereits wussten, wie dieser funktioniert. Es könnte jedoch ein Problem für Tab A sein, da Ihr V1-Code möglicherweise nicht vorhergesehen hat,welche Änderungen Ihr V2-Code mit sich bringen könnte.

Zur Bewältigung dieser Situationen sendet workbox-window auch Lebenszyklusereignisse, wenn ein Update von einem „externen“ Service Worker erkannt wird. „Extern“ bedeutet hier einfach jede Version, die nicht die Version der aktuell registrierten Workbox-Instanz ist.

Ab der Workbox Version 6 entsprechen diese Ereignisse den oben dokumentierten Ereignissen, allerdings wird für jedes Ereignisobjekt ein isExternal: true-Attribut festgelegt. Wenn Ihre Webanwendung eine bestimmte Logik zur Verarbeitung eines „externen“ Service Workers implementieren muss, können Sie in Ihren Event-Handlern nach dieser Eigenschaft suchen.

Häufige Fehler vermeiden

Eine der hilfreichsten Funktionen von Workbox ist die Protokollierung von Entwicklern. Dies gilt insbesondere für workbox-window.

Wir wissen, dass die Entwicklung mit Service Workern oft verwirrend sein kann. Wenn etwas nicht Ihren Erwartungen entspricht, lässt sich die Ursache oft nur schwer ermitteln.

Wenn Sie beispielsweise eine Änderung an Ihrem Service Worker vornehmen und die Seite neu laden, wird diese Änderung möglicherweise nicht in Ihrem Browser angezeigt. Der wahrscheinlichste Grund dafür ist, dass Ihr Service Worker immer noch auf die Aktivierung wartet.

Wenn Sie jedoch einen Service Worker für die Klasse Workbox registrieren, werden Sie über alle Änderungen des Lebenszyklusstatus in der Entwicklerkonsole informiert. Dies kann Ihnen bei der Fehlerbehebung helfen, wenn etwas nicht Ihren Erwartungen entspricht.

Darüber hinaus begehen Entwickler bei der ersten Verwendung eines Service Workers häufig den Fehler, einen Service Worker im falschen Bereich zu registrieren.

Um dies zu verhindern, werden Sie von der Klasse Workbox gewarnt, wenn die Seite, die den Service Worker registriert, nicht im Bereich dieses Service Workers liegt. Sie werden auch gewarnt, wenn Ihr Service Worker zwar aktiv ist, die Seite aber noch nicht steuert:

Kommunikation zwischen Fenster und Service Worker

Bei der fortschrittlichsten Service-Worker-Nutzung sind viele Nachrichten zwischen dem Service Worker und dem Fenster erforderlich. Die Klasse Workbox hilft ebenfalls dabei, indem sie die Methode messageSW() bereitstellt, die den registrierten Service Worker der Instanz mit einem postMessage()-Befehl beschäftigt und auf eine Antwort wartet.

Sie können zwar Daten in jedem Format an den Service Worker senden, das von allen Workbox-Paketen genutzte Format ist jedoch ein Objekt mit drei Eigenschaften (die beiden sind optional):

Nachrichten, die über die Methode messageSW() gesendet werden, verwenden MessageChannel, damit der Empfänger darauf antworten kann. Wenn Sie auf eine Nachricht antworten möchten, können Sie in Ihrem Nachrichtenereignis-Listener event.ports[0].postMessage(response) aufrufen. Die Methode messageSW() gibt ein Versprechen zurück, das in jede response aufgelöst wird, mit der du antwortest.

Hier ist ein Beispiel, wie Sie Nachrichten aus dem Fenster an den Service Worker senden und eine Antwort erhalten. Der erste Codeblock ist der Nachrichten-Listener im Service Worker und der zweite Block verwendet die Klasse Workbox, um die Nachricht zu senden und auf die Antwort zu warten:

Code in sw.js:

const SW_VERSION = '1.0.0';

addEventListener('message', event => {
  if (event.data.type === 'GET_VERSION') {
    event.ports[0].postMessage(SW_VERSION);
  }
});

Code in „main.js“ (wird im Fenster ausgeführt):

const wb = new Workbox('/sw.js');
wb.register();

const swVersion = await wb.messageSW({type: 'GET_VERSION'});
console.log('Service Worker version:', swVersion);

Versionsinkompatibilitäten verwalten

Das obige Beispiel zeigt, wie Sie die Prüfung der Service Worker-Version über das Fenster implementieren können. Dieses Beispiel wird verwendet, da Sie beim Senden von Nachrichten zwischen dem Fenster und dem Service Worker unbedingt beachten sollten, dass Ihr Service Worker möglicherweise nicht dieselbe Version Ihrer Website ausführt, mit der Ihr Seitencode ausgeführt wird. Die Lösung für dieses Problem hängt davon ab, ob Sie Ihre Seiten zuerst netzwerk- oder im Cache bereitstellen.

Netzwerk zuerst

Wenn die Anzeigen auf Ihren Seiten an erster Stelle im Netzwerk ausgeliefert werden, erhalten Nutzer immer die aktuelle HTML-Version von Ihrem Server. Wenn jedoch ein Nutzer Ihre Website zum ersten Mal besucht (nachdem Sie ein Update bereitgestellt haben), wird ihm der HTML-Code für die neueste Version angezeigt. Der im Browser ausgeführte Service Worker ist jedoch eine bereits installierte Version (möglicherweise alte).

Es ist wichtig, diese Möglichkeit zu verstehen. Wenn das von der aktuellen Version Ihrer Seite geladene JavaScript eine Nachricht an eine ältere Version des Service Workers sendet, weiß diese Version möglicherweise nicht, wie sie antworten soll, oder sie reagiert mit einem inkompatiblen Format.

Daher wird empfohlen, immer eine Version des Service Workers zu erstellen und nach kompatiblen Versionen zu suchen, bevor Sie wichtige Arbeiten ausführen.

Wenn im obigen Code beispielsweise die von diesem messageSW()-Aufruf zurückgegebene Service Worker-Version älter als die erwartete Version ist, sollten Sie warten, bis ein Update gefunden wurde. Dies sollte passieren, wenn Sie register() aufrufen. Sie können dann entweder den Nutzer oder ein Update benachrichtigen oder die Wartephase manuell überspringen, um den neuen Service Worker sofort zu aktivieren.

Zuerst im Cache speichern

Anders als wenn Sie Seiten netzwerkübergreifend bereitstellen, wissen Sie beim Bereitstellen des Cache für Ihre Seiten, dass Ihre Seite anfangs immer dieselbe Version wie der Service Worker hat (weil sie diese bereitgestellt hat). Daher kannst du messageSW() sofort verwenden.

Wenn jedoch eine aktualisierte Version Ihres Service Workers gefunden wird und aktiviert wird, wenn Ihre Seite register() aufruft (d.h. Sie überspringen die Wartephase absichtlich), ist es möglicherweise nicht mehr sicher, Nachrichten an sie zu senden.

Eine Strategie, um diese Möglichkeit zu umgehen, ist die Verwendung eines Versionsverwaltungsschemas, mit dem Sie zwischen funktionsgefährdenden und nicht funktionsgefährdenden Aktualisierungen unterscheiden können. Im Fall eines funktionsgefährdenden Updates würden Sie wissen, dass es nicht sicher ist, eine Nachricht an den Service Worker zu senden. Stattdessen sollten Sie den Nutzer warnen, dass er eine alte Version der Seite ausführt, und ihm vorschlagen, die Seite zu aktualisieren, um das Update zu erhalten.

Warteschleifenhilfe überspringen

Eine gängige Konvention für Window-to-Service-Worker-Messaging ist das Senden einer {type: 'SKIP_WAITING'}-Nachricht, um einen installierten Service Worker anzuweisen, die Wartezeit zu überspringen und zu aktivieren.

Ab Workbox v6 kann die Methode messageSkipWaiting() verwendet werden, um eine {type: 'SKIP_WAITING'}-Nachricht an den wartenden Service Worker zu senden, der mit der aktuellen Service Worker-Registrierung verknüpft ist. Ohne einen wartenden Service Worker erfolgt keine Meldung.

workbox-window.messageSW(
  sw: ServiceWorker,
  data: object,
)