Signatur
Beschreibung
Der Konstruktor new InstallEvent() erzeugt ein Ereignisobjekt vom Typ InstallEvent. Die Schnittstelle erweitert ExtendableEvent und steht für das install-Ereignis eines Service Workers. Sie erbt daher die Methode waitUntil(). Außerdem bringt sie (in Chromium) die Methode addRoutes() der Service Worker Static Routing API mit.
In der Praxis rufst du den Konstruktor fast nie selbst auf. Der Browser erzeugt das Ereignis automatisch, sobald ein neuer Service Worker installiert wird, und übergibt es an deinen install-Handler. Selbst anlegen lohnt sich vor allem für Unit-Tests und Polyfills oder um einen Installations-Handler gezielt noch einmal auszuführen.
Der Konstruktor ist nur im globalen Gültigkeitsbereich eines Service Workers (ServiceWorkerGlobalScope) verfügbar, nicht im window-Kontext. Ein selbst erzeugtes Ereignis löst keine echte Installation aus. Es ist ein gewöhnliches Ereignisobjekt, das du per dispatchEvent() an eigene Listener schicken kannst.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, üblicherweise "install". Groß- und Kleinschreibung wird beachtet. |
|
| $options | object | {} | Optionales Objekt vom Typ ExtendableEventInit. Es erbt von EventInit die Felder bubbles (Standard false), cancelable (Standard false) und composed (Standard false). Eigene Felder hat InstallEvent nicht. |
Rückgabewert
InstallEvent-Objekt mit dem angegebenen Typ und den übergebenen Optionen.Beispiele
InstallEvent im Service Worker erzeugen
// sw.js – läuft im ServiceWorkerGlobalScope
const event = new InstallEvent('install', { cancelable: false });
console.log(event.type);
console.log(event instanceof ExtendableEvent);
console.log(typeof event.waitUntil);Typische Nutzung: Dateien beim install-Ereignis vorab cachen
// sw.js
const CACHE_NAME = 'app-v1';
const ASSETS = ['/', '/index.html', '/styles.css', '/app.js'];
self.addEventListener('install', (event) => {
// Der Browser übergibt hier ein InstallEvent
console.log(event.constructor.name);
event.waitUntil(
(async () => {
const cache = await caches.open(CACHE_NAME);
await cache.addAll(ASSETS);
await self.skipWaiting();
})()
);
});Installations-Handler im Test manuell auslösen
// sw.js – Handler als eigene Funktion, damit er testbar ist
const onInstall = (event) => {
event.waitUntil(Promise.resolve().then(() => console.log('Installationslogik ausgeführt')));
};
self.addEventListener('install', onInstall);
// Test: selbst erzeugtes Ereignis an die eigenen Listener schicken
const fakeInstall = new InstallEvent('install');
self.dispatchEvent(fakeInstall);Statisches Routing mit addRoutes() (Chromium)
// sw.js
self.addEventListener('install', (event) => {
if ('addRoutes' in event) {
event.addRoutes({
condition: { urlPattern: new URLPattern({ pathname: '/api/*' }) },
source: 'network'
});
}
});// Wichtig · Fallstricke
- Experimentell:
InstallEventist in der Service-Worker-Spezifikation als eigene Schnittstelle nicht in allen Browsern umgesetzt. Firefox und Safari liefern beiminstall-Ereignis ein normalesExtendableEvent, dort istInstallEventnicht definiert. Prüfe vorher mittypeof InstallEvent !== 'undefined', ob die Schnittstelle vorhanden ist. Für browserübergreifenden Code verwendenew ExtendableEvent('install'). - Nur im Service Worker: Im
window- oder Web-Worker-Kontext wirft der Aufruf einenReferenceError. - Keine echte Installation: Ein selbst erzeugtes Ereignis stößt keinen Lebenszyklus-Wechsel an.
waitUntil()verlängert hier nichts im Browser. Außerhalb des Dispatch-Vorgangs kann es sogar einenInvalidStateErrorwerfen. isTrustedistfalse: Selbst erzeugte Ereignisse lassen sich von echten, vom Browser ausgelösten Ereignissen unterscheiden.addRoutes()gibt es bisher nur in Chromium (ab etwa Version 123). Du darfst die Methode nur während desinstall-Ereignisses aufrufen.