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 stellt ein Objekt dar, das den Service Worker als Gesamteinheit im Netzwerk-Ökosystem repräsentiert, inklusive Funktionen zum Registrieren, Deregistrieren und Aktualisieren von Service Workern sowie zum Zugriff auf den Status der Service Worker und ihrer Registrierungen.

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

ServiceWorkerContainer-Objekte werden im Fensterbereich über Navigator.serviceWorker und in Workern mithilfe von WorkerNavigator.serviceWorker bereitgestellt (falls unterstützt — siehe Browser-Kompatibilität).

Instanzeigenschaften

ServiceWorkerContainer.controller Schreibgeschützt: Gibt ein ServiceWorker-Objekt zurück, wenn sein Status activating oder activated ist (dasselbe Objekt, das von ServiceWorkerRegistration.active zurückgegeben wird). Diese Eigenschaft gibt null zurück während einer erzwungenen Aktualisierungsanfrage (Shift + Aktualisierung) oder wenn kein aktiver Worker vorhanden ist.
ServiceWorkerContainer.ready Schreibgeschützt: Bietet eine Möglichkeit, die Codeausführung zu verzögern, bis ein Service Worker aktiv ist. Es gibt ein Promise zurück, das niemals abgelehnt wird und das unbegrenzt wartet, bis die ServiceWorkerRegistration, die mit der aktuellen Seite verknüpft ist, einen ServiceWorkerRegistration.active Worker hat. Sobald diese Bedingung erfüllt ist, wird sie mit der ServiceWorkerRegistration aufgelöst.

Instanzmethoden

ServiceWorkerContainer.getRegistration(): Ruft ein ServiceWorkerRegistration-Objekt ab, dessen Umfang mit der angegebenen Dokument-URL übereinstimmt. 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 explizit den Nachrichtenfluss, der von einem Service Worker an die von ihm kontrollierten Seiten gesendet wird (z. B. gesendet über Client.postMessage()). Dies kann verwendet werden, um auf gesendete Nachrichten früher zu reagieren, noch bevor der Inhalt dieser Seite vollständig geladen wurde.

Ereignisse

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

Beispiele

Im folgenden Beispiel wird zunächst überprüft, ob der Browser Service Worker unterstützt. Wenn dies der Fall ist, registriert der Code den Service Worker und stellt fest, 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