ServiceWorkerContainer

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.

* Some parts of this feature may have varying levels of support.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Das ServiceWorkerContainer-Interface der Service Worker API bietet ein Objekt, das den Service Worker als gesamte Einheit im Netzwerk-Ökosystem repräsentiert. Es umfasst Funktionen zum Registrieren, Deregistrieren und Aktualisieren von Service Workern sowie den Zugriff auf den Status von Service Workern und deren Registrierungen.

Am wichtigsten ist, dass es die Methode ServiceWorkerContainer.register() bereitstellt, die zum Registrieren von Service Workern verwendet wird, und die Eigenschaft ServiceWorkerContainer.controller, mit der bestimmt wird, ob die aktuelle Seite aktiv gesteuert wird.

ServiceWorkerContainer-Objekte sind im Fensterbereich über Navigator.serviceWorker und in Arbeitern über WorkerNavigator.serviceWorker verfügbar (falls unterstützt — siehe Browser-Kompatibilität).

Instanz-Eigenschaften

ServiceWorkerContainer.controller Schreibgeschützt: Ein ServiceWorker-Objekt, das den aktiven Service Worker repräsentiert, der die aktuelle Seite steuert, oder null, wenn die Seite keinen aktiven oder aktivierenden Service Worker hat.
ServiceWorkerContainer.ready Schreibgeschützt: Gibt ein Promise zurück, das mit der ServiceWorkerRegistration aufgelöst wird, die mit der aktuellen Seite verknüpft ist, jedoch nur, wenn ein aktiver Service Worker existiert. Dies bietet einen Mechanismus, um die Codeausführung zu verzögern, bis ein Service Worker aktiv ist.

Instanz-Methoden

ServiceWorkerContainer.getRegistration(): Erhält ein ServiceWorkerRegistration-Objekt, dessen Geltungsbereich zur angegebenen Dokument-URL passt. Die Methode gibt ein Promise zurück, das zu einer ServiceWorkerRegistration oder undefined aufgelöst wird.
ServiceWorkerContainer.getRegistrations(): Gibt alle ServiceWorkerRegistration-Objekte zurück, die mit einem ServiceWorkerContainer in einem Array verknüpft sind. Die Methode gibt ein Promise zurück, das zu einem Array von ServiceWorkerRegistration aufgelöst wird.
ServiceWorkerContainer.register(): Erstellt oder aktualisiert eine ServiceWorkerRegistration für die angegebene scriptURL.
ServiceWorkerContainer.startMessages(): Startet ausdrücklich den Fluss von Nachrichten, die von einem Service Worker zu Seiten gesendet werden, die unter seiner Kontrolle stehen (z.B. gesendet über Client.postMessage()). Dies kann verwendet werden, um früher auf gesendete Nachrichten zu reagieren, noch bevor der Inhalt der Seite vollständig geladen ist.

Ereignisse

controllerchange: Wird ausgelöst, wenn die dem Dokument zugeordnete ServiceWorkerRegistration einen neuen active Worker erhält.
message: Wird ausgelöst, wenn eingehende Nachrichten vom ServiceWorkerContainer-Objekt empfangen werden (z.B. über einen Aufruf von MessagePort.postMessage()).
messageerror: Wird ausgelöst, wenn eingehende Nachrichten vom ServiceWorkerContainer-Objekt nicht deserialisiert werden können (z.B. über einen Aufruf von MessagePort.postMessage()).

Beispiele

Das folgende Beispiel prüft zunächst, ob der Browser Service Worker unterstützt. Wenn Unterstützung vorhanden ist, registriert der Code den Service Worker und bestimmt, ob die Seite aktiv vom Service Worker gesteuert wird. Falls nicht, wird der Benutzer aufgefordert, die Seite neu zu laden, damit der Service Worker die Kontrolle übernehmen kann. Der Code meldet auch Registrierungsfehler.

if ("serviceWorker" in navigator) {
  // Register a service worker hosted at the root of the
  // site using the default scope.
  navigator.serviceWorker
    .register("/sw.js")
    .then((registration) => {
      console.log("Service worker registration succeeded:", registration);

      // At this point, you can optionally do something
      // with registration. See https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration
    })
    .catch((error) => {
      console.error(`Service worker registration failed: ${error}`);
    });

  // Independent of the registration, let's also display
  // information about whether the current page is controlled
  // by an existing service worker, and when that
  // controller changes.

  // First, do a one-off check if there's currently a
  // service worker in control.
  if (navigator.serviceWorker.controller) {
    console.log(
      "This page is currently controlled by:",
      navigator.serviceWorker.controller,
    );
  }

  // Then, register a handler to detect when a new or
  // updated service worker takes control.
  navigator.serviceWorker.oncontrollerchange = () => {
    console.log(
      "This page is now controlled by",
      navigator.serviceWorker.controller,
    );
  };
} else {
  console.log("Service workers are not supported.");
}

Spezifikationen

Specification
Service Workers # serviceworkercontainer-interface