Signatur
Beschreibung
addRoutes() gehört zur Service Worker Static Routing API. Im install-Handler legt man damit eine oder mehrere Regeln fest. Jede Regel besteht aus einer condition (Bedingung) und einer source (Quelle). Der Browser wertet die Regeln direkt aus, also ohne JavaScript im Service Worker auszuführen. Er kann eine Anfrage darum ans Netzwerk oder an den Cache weiterleiten, ohne den Service Worker erst zu starten.
Der Hauptvorteil ist Geschwindigkeit. Ein Service Worker, der gerade nicht läuft, braucht einige Millisekunden bis zum Start. Sind Anfragen ohnehin fürs Netzwerk bestimmt (z. B. API-Aufrufe oder große Mediendateien), wäre dieser Start reine Verzögerung. Statische Routen umgehen ihn. Sie eignen sich auch, um Ressourcen direkt aus einem bestimmten Cache zu liefern oder Netzwerk und fetch-Handler gegeneinander antreten zu lassen ("race-network-and-fetch-handler").
Die Regeln werden der Reihe nach geprüft. Die erste passende Regel gewinnt. Passt keine Regel, läuft die Anfrage wie gewohnt über den fetch-Handler. Mögliche Bedingungen sind urlPattern, requestMethod, requestMode, requestDestination und runningStatus. Mit or und not lassen sie sich logisch verknüpfen.
Die Regeln gelten für die gesamte Lebensdauer dieser Service-Worker-Version. Ändern lassen sie sich nur, indem man eine neue Version installiert. addRoutes() kann man nur während des install-Events aufrufen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $routerRules Pflicht | RouterRule | RouterRule[] | Eine einzelne Regel oder ein Array von Regeln. Jede Regel ist ein Objekt mit den Eigenschaften condition und source. |
|
| $routerRules[].condition Pflicht | object | Bedingungen, die alle erfüllt sein müssen (UND-Verknüpfung):
or und not dürfen nicht mit anderen Schlüsseln in derselben Bedingung stehen. |
|
| $routerRules[].source Pflicht | string | { cacheName: string } | Woher die Antwort kommt:
|
Rückgabewert
TypeError abgelehnt. Gründe sind z. B. eine falsche Quelle, "fetch-event" ohne registrierten fetch-Handler, zu tiefe Verschachtelung oder ein ungültiges URL-Muster.Beispiele
API-Anfragen direkt ans Netzwerk schicken
// sw.js
self.addEventListener('install', (event) => {
event.waitUntil(
event.addRoutes({
condition: { urlPattern: '/api/*' },
source: 'network'
})
);
});
self.addEventListener('fetch', (event) => {
// Wird für /api/* nicht mehr aufgerufen
console.log('fetch-Handler:', event.request.url);
});Statische Dateien aus einem bestimmten Cache liefern
// sw.js
const CACHE = 'static-v2';
self.addEventListener('install', (event) => {
event.waitUntil((async () => {
const cache = await caches.open(CACHE);
await cache.addAll(['/css/app.css', '/js/app.js', '/img/logo.svg']);
await event.addRoutes([
{
condition: {
or: [
{ requestDestination: 'style' },
{ requestDestination: 'script' },
{ requestDestination: 'image' }
]
},
source: { cacheName: CACHE }
}
]);
})());
});Seitenaufrufe je nach Laufzustand des Service Workers routen
// sw.js
self.addEventListener('install', (event) => {
event.waitUntil(
event.addRoutes([
{
// Läuft der SW nicht: Netzwerk und Handler parallel starten
condition: { requestMode: 'navigate', runningStatus: 'not-running' },
source: 'race-network-and-fetch-handler'
},
{
// Alles außer GET direkt ins Netz
condition: { not: { requestMethod: 'GET' } },
source: 'network'
}
])
);
});
self.addEventListener('fetch', (event) => {
event.respondWith(
caches.match(event.request).then((r) => r ?? fetch(event.request))
);
});Unterstützung vor dem Aufruf prüfen
// sw.js
self.addEventListener('install', (event) => {
if (typeof event.addRoutes !== 'function') {
console.log('Static Routing API nicht verfügbar – fetch-Handler übernimmt');
return;
}
event.waitUntil(
event.addRoutes({
condition: { urlPattern: new URLPattern({ pathname: '/videos/*' }) },
source: 'network'
}).catch((err) => console.error('Ungültige Route:', err))
);
});