Signatur
Beschreibung
Die Methode disable() der Schnittstelle NavigationPreloadManager deaktiviert das Navigation Preload, das zuvor mit enable() eingeschaltet wurde. Ist Navigation Preload aktiv, schickt der Browser Navigationsanfragen schon ab, während der Service Worker noch startet. Die Antwort steht danach im fetch-Handler über event.preloadResponse bereit. Nach disable() gibt es diese Parallelanfrage nicht mehr, und event.preloadResponse wird zu undefined aufgelöst.
Deaktivieren lohnt sich, wenn der Service Worker Navigationen ohnehin vollständig aus dem Cache beantwortet, zum Beispiel bei App-Shell- oder Offline-first-Strategien. Die vorab geladene Antwort würde dann nie verwendet und nur Bandbreite sowie Serverlast kosten.
Aufgerufen wird die Methode über registration.navigationPreload, meist im activate-Handler des Service Workers oder im Seitenkontext über navigator.serviceWorker.ready. Die Einstellung wird für die Registrierung gespeichert und bleibt bestehen, bis erneut enable() aufgerufen wird.
Rückgabewert
undefined erfüllt wird, sobald Navigation Preload deaktiviert ist. Es wird mit einem InvalidStateError (DOMException) abgelehnt, wenn die Registrierung keinen aktiven Worker hat.Beispiele
Navigation Preload im activate-Handler abschalten
// sw.js
self.addEventListener('activate', (event) => {
event.waitUntil((async () => {
if (self.registration.navigationPreload) {
await self.registration.navigationPreload.disable();
console.log('Navigation Preload deaktiviert');
}
})());
});Aus dem Seitenkontext deaktivieren und Zustand prüfen
// main.js
const turnOffPreload = async () => {
if (!('serviceWorker' in navigator)) return;
const registration = await navigator.serviceWorker.ready;
if (!registration.navigationPreload) {
console.log('Navigation Preload wird nicht unterstützt');
return;
}
await registration.navigationPreload.disable();
const state = await registration.navigationPreload.getState();
console.log(state);
};
turnOffPreload();Je nach Cache-Strategie umschalten
// sw.js: Preload nur nutzen, wenn keine App-Shell im Cache liegt
const SHELL_CACHE = 'app-shell-v2';
self.addEventListener('activate', (event) => {
event.waitUntil((async () => {
const np = self.registration.navigationPreload;
if (!np) return;
const cache = await caches.open(SHELL_CACHE);
const hasShell = await cache.match('/index.html');
if (hasShell) {
await np.disable(); // Navigationen kommen aus dem Cache
} else {
await np.enable(); // Netzwerk parallel zum Worker-Start
}
})());
});
self.addEventListener('fetch', (event) => {
if (event.request.mode !== 'navigate') return;
event.respondWith((async () => {
const cached = await caches.match('/index.html');
if (cached) return cached;
// Bei deaktiviertem Preload wird dies zu undefined aufgelöst
const preloaded = await event.preloadResponse;
return preloaded ?? fetch(event.request);
})());
});// Wichtig · Fallstricke
- Aktiver Worker nötig: Ohne aktiven Service Worker wird das Promise mit
InvalidStateErrorabgelehnt. Iminstall-Handler ist deshalb Vorsicht geboten; deractivate-Handler ist der richtige Ort. - Funktionen prüfen: Vor dem Aufruf prüfen, ob
registration.navigationPreloadexistiert. Ältere Browser, etwa Firefox vor Version 99 oder Safari vor 15.4, kennen die Eigenschaft nicht. - Dauerhafte Einstellung: Die Einstellung gilt für die Registrierung und bleibt über Neustarts des Workers hinweg bestehen. Wer sie nur vorübergehend abschaltet, muss später selbst wieder
enable()aufrufen. - Kein Einfluss auf laufende Anfragen: Bereits gestartete Preload-Anfragen werden nicht abgebrochen. Die Einstellung wirkt erst bei folgenden Navigationen.
- Nur in sicheren Kontexten (HTTPS oder
localhost) verfügbar, wie alle Service-Worker-APIs.