ServiceWorkerContainer: register()-Methode

Syntax

register(scriptURL)
register(scriptURL, options)

Parameter

scriptURL

Die URL des Servicearbeiter-Skripts. Die registrierte Servicearbeiter-Datei muss einen gültigen JavaScript MIME-Typ haben.

options Optional

Ein Objekt, das Registrierungsoptionen enthält. Derzeit verfügbare Optionen sind:

scope

Ein String, der eine URL darstellt, die den Registrierungsbereich (scope) eines Servicearbeiters definiert, d.h. welchen Bereich von URLs ein Servicearbeiter kontrollieren kann.

Dies wird normalerweise als URL angegeben, die relativ zur Basis-URL der Website ist (z. B. /some/path/), sodass der aufgelöste Geltungsbereich unabhängig davon, von welcher Seite der Registrierungscode aufgerufen wird, derselbe ist. Der Standard-scope für eine Servicearbeiter-Registrierung ist das Verzeichnis, in dem sich das Servicearbeiter-Skript befindet (resolving ./ gegen scriptURL).

Der Geltungsbereich sollte genutzt werden, um Dokumente zu spezifizieren, die sich im selben Verzeichnis oder tiefer verschachtelt als der Servicearbeiter befinden. Wenn Sie einen breiteren Geltungsbereich benötigen, kann dies über den HTTP-Service-Worker-Allowed-Header gestattet werden. Siehe den Abschnitt Beispiele für Informationen zur Erweiterung des Standard-Geltungsbereichs eines Servicearbeiters.

type

Ein String, der den Typ des zu erstellenden Arbeiters angibt. Gültige Werte sind:

'classic'

Der geladene Servicearbeiter ist in einem Standardskript. Dies ist der Standard.

'module'

Der geladene Servicearbeiter ist in einem ES-Modul und die Import-Anweisung ist in Arbeiter-Kontexten verfügbar. Für Informationen zur ES-Modul-Kompatibilität siehe die Tabelle zur Browser-Kompatibilität für das ServiceWorker-Interface.

updateViaCache

Ein String, der angibt, wie der HTTP-Cache für Servicearbeiter-Skriptressourcen während der Aktualisierungen verwendet wird. Hinweis: Dies bezieht sich nur auf das Servicearbeiter-Skript und seine Importe, nicht auf andere von diesen Skripten abgerufene Ressourcen.

'all'

Der HTTP-Cache wird sowohl für das Hauptskript als auch für alle importierten Skripte abgefragt. Wenn im HTTP-Cache kein aktueller Eintrag gefunden wird, werden die Skripte aus dem Netzwerk abgerufen.

'imports'

Der HTTP-Cache wird für Importe abgefragt, aber das Hauptskript wird immer aus dem Netzwerk aktualisiert. Wenn kein aktueller Eintrag im HTTP-Cache für die Importe gefunden wird, werden sie aus dem Netzwerk abgerufen.

'none'

Der HTTP-Cache wird weder für das Hauptskript noch für dessen Importe genutzt. Alle Servicearbeiter-Skriptressourcen werden aus dem Netzwerk aktualisiert.

Rückgabewert

Ein Promise, der mit einem ServiceWorkerRegistration-Objekt aufgelöst wird.

Ausnahmen

TypeError

Die scriptURL oder scope URL schlägt fehl. Dies kann passieren, wenn die URL nicht in eine gültige URL aufgelöst werden kann oder ein Schema verwendet, das nicht http: oder https ist. Es kann auch passieren, wenn scriptURL keine TrustedScriptURL ist, und dies eine Anforderung der Trusted Types Policy der Seite ist.

Die Ausnahme wird auch ausgelöst, wenn der scriptURL- oder scope URL-Pfad die ASCII-Zeichenfolge "%2f" (*) oder "%5c" (=) case-insensitive enthält.

SecurityError DOMException

Die scriptURL stammt nicht aus einer potenziell vertrauenswürdigen Quelle, wie z. B. localhost oder eine https-URL. Die scriptURL und der Geltungsbereich sind nicht gleichursprungsberechtigt mit der registrierenden Seite.

Beispiele

Die folgenden Beispiele sollten zusammen gelesen werden, um zu verstehen, wie der Geltungsbereich eines Servicearbeiters auf eine Seite angewendet wird.

Registrierung eines Servicearbeiters mit Standard-Geltungsbereich

Das folgende Beispiel verwendet den Standardwert für scope, indem es ihn weglässt, wodurch er auf denselben Ort wie die Skript-URL gesetzt wird.

Angenommen, der Servicearbeiter-Code befindet sich bei example.com/sw.js und der Registrierungscode bei example.com/index.html. Der Servicearbeiter-Code wird example.com/index.html kontrollieren sowie Seiten darunter, wie example.com/product/description.html.

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);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Beachten Sie, dass wir die scriptURL relativ zum Wurzelverzeichnis der Website und nicht zur aktuellen Seite registriert haben. Dies ermöglicht es, denselben Registrierungscode von jeder Seite aus zu verwenden.

Registrierung eines Servicearbeiters mit explizitem Standard-Geltungsbereich

Der untenstehende Code ist fast identisch, außer dass wir den Geltungsbereich explizit mit { scope: "/" } angegeben haben. Wir haben den Geltungsbereich relativ zur Website angegeben, sodass derselbe Registrierungscode von überall auf der Website aus verwendet werden kann.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "/" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Dieser Geltungsbereich ist derselbe wie der Standard-Geltungsbereich, sodass die Registrierung auf genau dieselben Seiten wie im vorherigen Beispiel zutrifft. Beachten Sie, dass, wenn wir diesen Code nach dem vorherigen Beispiel ausführen würden, Browser erkennen sollten, dass wir eine bestehende Registrierung aktualisieren und nicht eine neue erstellen.

Registrierung eines Servicearbeiters mit seitenrelativen URLs

Es gibt nichts, was Sie daran hindert, seitenrelative URLs zu verwenden, außer dass dies das Verschieben Ihrer Seiten erschwert, und es ist leicht, versehentlich unerwünschte Registrierungen zu erstellen, wenn Sie dies tun.

In diesem Beispiel befindet sich der Servicearbeiter-Code unter example.com/product/sw.js und der Registrierungscode bei example.com/product/description.html. Wir verwenden URLs, die relativ zum aktuellen Verzeichnis sind, für die scriptURL und den scope, wobei das aktuelle Verzeichnis die Basis-URL der Seite ist, die register() aufruft (example.com/product/). Der Servicearbeiter gilt für Ressourcen unter example.com/product/.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "./" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Verwendung von Service-Worker-Allowed zur Erhöhung des Servicearbeiter-Geltungsbereichs

Ein Servicearbeiter kann keinen breiteren Geltungsbereich als seinen eigenen Standort haben, es sei denn, der Server legt in einem Service-Worker-Allowed-Header auf dem Servicearbeiter-Skript einen breiteren maximalen Geltungsbereich fest. Verwenden Sie die scope-Option, wenn Sie einen enger Geltungsbereich als den Standard benötigen.

Der folgende Code, wenn er in example.com/index.html am Wurzelverzeichnis einer Website enthalten ist, würde nur auf Ressourcen unter example.com/product zutreffen.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "/product/" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Wie oben erwähnt, können Server den Standard-Geltungsbereich ändern, indem sie den Service-Worker-Allowed-Header auf dem Servicearbeiter-Skript setzen. Dies ermöglicht es, die scope-Option außerhalb des durch den Standort des Servicearbeiters definierten Pfades zu setzen.

Der folgende Code, wenn er in example.com/product/index.html enthalten ist, würde auf alle Ressourcen unter example.com zutreffen, wenn der Server den Service-Worker-Allowed-Header auf / oder https://example.com/ setzt, wenn sw.js bereitgestellt wird. Wenn der Server diesen Header nicht setzt, schlägt die Registrierung des Servicearbeiters fehl, da der angeforderte scope zu breit ist.

if ("serviceWorker" in navigator) {
  // Declaring a broadened scope
  navigator.serviceWorker.register("./sw.js", { scope: "/" }).then(
    (registration) => {
      // The registration succeeded because the Service-Worker-Allowed header
      // had set a broadened maximum scope for the service worker script
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      // This happens if the Service-Worker-Allowed header doesn't broaden the scope
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• ServiceWorkerRegistration: unregister()-Methode
• Service Worker API
• Verwendung von Servicearbeitern
• Service-Worker-Allowed HTTP-Header