NavigationPreloadManager.enable() — Methode · JavaScript-Referenz

Signatur

NavigationPreloadManager.prototype.enable()

Beschreibung

enable() schaltet Navigation Preload für eine Service-Worker-Registrierung ein. Ist die Funktion aktiv, schickt der Browser bei einer Navigation (also beim Laden einer Seite) die Anfrage schon ans Netzwerk, während der Service Worker noch startet. Die Antwort steht dann im fetch-Handler über event.preloadResponse bereit.

Das lohnt sich vor allem bei Strategien nach dem Muster Network-first oder Network-only für HTML-Seiten. Ohne Preload muss der Browser erst den Service Worker hochfahren. Das kann auf Mobilgeräten mehrere hundert Millisekunden dauern, und erst danach startet die Netzwerkanfrage. Mit Preload laufen beide Schritte parallel, die Wartezeit fällt also weg.

Aufgerufen wird die Methode fast immer im activate-Event des Service Workers, und zwar über self.registration.navigationPreload.enable(). Weil sie ein Promise zurückgibt, übergibt man sie an event.waitUntil(). So bleibt der Service Worker aktiv, bis die Einstellung gespeichert ist. Die Einstellung gilt für die ganze Registrierung und bleibt erhalten, bis disable() aufgerufen wird.

Wichtig: Wenn Preload aktiv ist, sollte der fetch-Handler event.preloadResponse auch nutzen. Sonst verschwendet man Bandbreite, und der Browser meldet in der Konsole eine Warnung, weil die vorgeladene Anfrage abgebrochen wurde.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald Navigation Preload aktiviert ist. Es wird mit einer InvalidStateError-DOMException abgelehnt, wenn die Registrierung keinen aktiven Service Worker hat.

Beispiele

Navigation Preload im activate-Event aktivieren

// sw.js
self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    // Feature-Erkennung: nicht jeder Browser kennt navigationPreload
    if (self.registration.navigationPreload) {
      await self.registration.navigationPreload.enable();
      console.log('Navigation Preload aktiviert');
    }
  })());
});

Navigation Preload aktiviert

Vorgeladene Antwort im fetch-Handler verwenden

// sw.js
self.addEventListener('fetch', (event) => {
  if (event.request.mode !== 'navigate') return;

  event.respondWith((async () => {
    try {
      // 1. Vorgeladene Antwort nutzen, falls vorhanden
      const preloaded = await event.preloadResponse;
      if (preloaded) return preloaded;

      // 2. Sonst normal übers Netzwerk laden
      return await fetch(event.request);
    } catch (err) {
      // 3. Offline: Fallback-Seite aus dem Cache
      const cache = await caches.open('offline-v1');
      return cache.match('/offline.html');
    }
  })());
});

Aktivieren mit eigenem Header-Wert und Status prüfen

// sw.js
self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    const np = self.registration.navigationPreload;
    if (!np) return;

    await np.enable();
    // Server kann am Header 'Service-Worker-Navigation-Preload' erkennen,
    // dass es sich um eine Preload-Anfrage handelt (z. B. nur Seiteninhalt liefern)
    await np.setHeaderValue('content-only');

    const state = await np.getState();
    console.log(state);
  })());
});

{ enabled: true, headerValue: 'content-only' }

// Wichtig · Fallstricke

Nur mit aktivem Service Worker: Wird enable() ohne aktiven Worker aufgerufen, zum Beispiel zu früh im install-Event, lehnt das Promise mit InvalidStateError ab. Der richtige Ort ist deshalb das activate-Event.
preloadResponse immer verwenden: Ist Preload aktiv, aber der fetch-Handler nutzt die Antwort nicht, lädt der Browser die Seite doppelt. Kommen alle Seiten ohnehin aus dem Cache (Cache-first), bringt Preload nichts. Dann sollte man es besser nicht aktivieren.
Kein respondWith(), trotzdem nutzen: Ruft der Handler event.respondWith() nicht auf, sollte er event.waitUntil(event.preloadResponse) aufrufen. Sonst kann die Preload-Anfrage abgebrochen werden.
Server-Seite: Preload-Anfragen enthalten den Header Service-Worker-Navigation-Preload, standardmäßig mit dem Wert true. Wenn der Server die Antwort je nach diesem Header anpasst, muss er Vary: Service-Worker-Navigation-Preload setzen, damit Caches die Varianten auseinanderhalten.
Kompatibilität: Chromium-Browser unterstützen die Methode seit Langem. Firefox kann sie erst ab Version 99, Safari erst ab 15.4. Vor dem Aufruf sollte man daher immer prüfen, ob self.registration.navigationPreload vorhanden ist. Die Methode gibt es nur in sicheren Kontexten (HTTPS).

Siehe auch

NavigationPreloadManager.disable() NavigationPreloadManager.getState() NavigationPreloadManager.setHeaderValue() Navigation.reload() Navigator.javaEnabled()