Signatur
Beschreibung
Die schreibgeschützte Eigenschaft navigationPreload gibt das NavigationPreloadManager-Objekt der aktuellen Registrierung zurück. Mit diesem Objekt schaltet man Navigation Preload ein oder aus und setzt den Wert des HTTP-Headers Service-Worker-Navigation-Preload.
Navigation Preload löst ein Leistungsproblem: Wenn ein Service Worker erst gestartet werden muss, verzögert sich jede Navigationsanfrage, bis der fetch-Handler läuft. Mit Preload startet der Browser die Netzwerkanfrage parallel zum Start des Service Workers. Im fetch-Handler bekommt man die Antwort dann über event.preloadResponse.
Meist aktiviert man Preload im activate-Event des Service Workers mit self.registration.navigationPreload.enable(). Man kann die Eigenschaft aber auch in der Seite abfragen, zum Beispiel über navigator.serviceWorker.ready. Sinnvoll ist Preload vor allem dann, wenn der Service Worker Navigationen ohnehin meistens über das Netzwerk beantwortet (Network-first).
Rückgabewert
NavigationPreloadManager dieser Registrierung. Er bietet die Methoden enable(), disable(), setHeaderValue() und getState(), die alle ein Promise zurückgeben.Beispiele
Preload im activate-Event aktivieren (sw.js)
// sw.js
self.addEventListener('activate', (event) => {
event.waitUntil((async () => {
// Feature-Erkennung: nicht jeder Browser unterstützt Preload
if (self.registration.navigationPreload) {
await self.registration.navigationPreload.enable();
console.log('Navigation Preload aktiviert');
}
})());
});preloadResponse im fetch-Handler verwenden
// sw.js
self.addEventListener('fetch', (event) => {
if (event.request.mode !== 'navigate') return;
event.respondWith((async () => {
try {
// Vorab geladene Antwort nutzen, falls vorhanden
const preloaded = await event.preloadResponse;
if (preloaded) return preloaded;
return await fetch(event.request);
} catch (err) {
// Offline-Rückfall aus dem Cache
const cache = await caches.open('offline-v1');
return (await cache.match('/offline.html')) ?? Response.error();
}
})());
});Status aus der Seite abfragen und eigenen Header setzen
// main.js (Seitenkontext)
const checkPreload = async () => {
const registration = await navigator.serviceWorker.ready;
const manager = registration.navigationPreload;
if (!manager) {
console.log('Navigation Preload nicht unterstützt');
return;
}
// Der Server kann diesen Header auswerten und z. B. nur Inhalte liefern
await manager.setHeaderValue('content-only');
const state = await manager.getState();
console.log(state);
};
checkPreload();// Wichtig · Fallstricke
- Feature-Erkennung: Ältere Browser (Firefox vor 99, Safari vor 15.4) kennen die Eigenschaft nicht, dort ist sie
undefined. Deshalb vor der Nutzung immer mitif (registration.navigationPreload)prüfen. - preloadResponse nicht ignorieren: Ist Preload aktiv, fragt der Browser das Netzwerk in jedem Fall an. Wenn der
fetch-Handlerevent.preloadResponsenicht verwendet, wird die Anfrage doppelt gesendet. Dann zeigt Chrome eine Warnung in der Konsole an. enable()unddisable()funktionieren nur mit einem aktiven Service Worker. Deshalb ruft man sie am besten inactivateauf und bindet sie mitevent.waitUntil()ein.- Preload gilt nur für Navigationsanfragen (
request.mode === 'navigate'), nicht für Unterressourcen wie Bilder oder Skripte. - Der Server bekommt standardmäßig den Header
Service-Worker-Navigation-Preload: true. Wenn die Antwort je nach Header unterschiedlich ausfällt, sollte erVary: Service-Worker-Navigation-Preloadsetzen, damit keine falschen Antworten aus dem Cache kommen. - Die Eigenschaft ist nur in sicheren Kontexten (HTTPS oder localhost) verfügbar.