ServiceWorkerContainer

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

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Das ServiceWorkerContainer-Interface der Service Worker API bietet ein Objekt, das den Service Worker als Gesamteinheit im Netzwerkökosystem darstellt. Es umfasst Möglichkeiten zur Registrierung, Deregistrierung und Aktualisierung von Service Workern sowie zum Zugriff auf den Status der Service Worker und deren Registrierungen.

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

ServiceWorkerContainer-Objekte sind im Fensterscope über Navigator.serviceWorker und in Worker-Threads mithilfe von WorkerNavigator.serviceWorker verfügbar (falls unterstützt - siehe Browser-Kompatibilität).

EventTarget ServiceWorkerContainer

Instanz-Eigenschaften

ServiceWorkerContainer.controller Nur lesbar

Gibt ein ServiceWorker-Objekt zurück, wenn dessen Status activating oder activated ist (dasselbe Objekt, das von ServiceWorkerRegistration.active zurückgegeben wird). Diese Eigenschaft gibt null zurück während einer erzwungenen Neuladung (Shift + Aktualisieren) oder wenn kein aktiver Worker vorhanden ist.

ServiceWorkerContainer.ready Nur lesbar

Bietet eine Möglichkeit, die Ausführung von Code zu verzögern, bis ein Service Worker aktiv ist. Es liefert ein Promise zurück, das niemals abgelehnt wird und unbegrenzt wartet, bis die ServiceWorkerRegistration der aktuellen Seite einen aktiven ServiceWorkerRegistration.active Worker hat. Sobald diese Bedingung erfüllt ist, wird es mit der ServiceWorkerRegistration aufgelöst.

Instanz-Methoden

ServiceWorkerContainer.getRegistration()

Ruft ein ServiceWorkerRegistration-Objekt ab, dessen Scope 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 verbunden 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 Inhalts der Seite vollständig geladen ist.

Ereignisse

controllerchange

Wird ausgelöst, wenn die der Seite zugeordnete ServiceWorkerRegistration einen neuen active Worker erwirbt.

error Veraltet Nicht standardisiert

Wird ausgelöst, wenn ein Fehler in den zugeordneten Service Workern auftritt.

message

Wird ausgelöst, wenn eingehende Nachrichten von dem ServiceWorkerContainer-Objekt empfangen werden (z.B. durch einen Aufruf von MessagePort.postMessage()).

messageerror

Wird ausgelöst, wenn eingehende Nachrichten vom ServiceWorkerContainer-Objekt nicht deserialisiert werden können (z.B. durch einen Aufruf von MessagePort.postMessage()).

Beispiele

Im folgenden Beispiel wird zunächst überprüft, ob der Browser Service Worker unterstützt. Wenn unterstützt, 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 alle Registrierungsfehler.

js
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

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch