InstallEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface InstallEvent extends ExtendableEvent

Beschreibung

InstallEvent ist das Objekt, das ein install-Handler im Service Worker bekommt. Der Browser löst das Ereignis genau einmal pro neuer Service-Worker-Version aus, und zwar direkt nach dem erfolgreichen Herunterladen und Parsen des Skripts. Die Schnittstelle erbt von ExtendableEvent und ist damit im Kern ein Event mit der Methode waitUntil().

Die Installationsphase eignet sich vor allem für das Vorab-Cachen (Precaching) der App-Shell, also HTML, CSS, JavaScript, Schriften und Icons, die offline verfügbar sein sollen. Mit event.waitUntil(promise) hält der Service Worker die Installation so lange offen, bis das Promise erfüllt ist. Wird das Promise abgelehnt, scheitert die Installation. Der neue Worker wird dann verworfen und der alte bleibt aktiv.

Zusätzlich gibt es in Chromium-Browsern die experimentelle Methode addRoutes() aus der Service Worker Static Routing API. Mit ihr legt man fest, welche Anfragen der Browser direkt aus dem Netz oder Cache bedient, ohne den Service Worker zu starten. Nach der Installation geht der Worker in den Zustand installed/„waiting“ und wartet, bis kein Tab mehr die alte Version nutzt. Nur self.skipWaiting() überspringt diese Wartezeit.

Einen Handler meldet man entweder mit self.addEventListener('install', handler) an oder über die Eigenschaft self.oninstall.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur für den Konstruktor `new InstallEvent(type, options)`: Name des Ereignisses, in der Regel `'install'`.
$options	object	{}	Nur für den Konstruktor: Optionen wie bei `ExtendableEvent` bzw. `Event`, also `bubbles`, `cancelable` und `composed`.

Rückgabewert

Typ

InstallEvent

Beschreibung

Ein Ereignisobjekt mit den geerbten Methoden waitUntil(promise) (von ExtendableEvent) und den Eigenschaften von Event. In Chromium kommt noch addRoutes(rules) hinzu, das ein Promise<void> zurückgibt.

Beispiele

App-Shell beim Installieren vorab cachen

// sw.js
const CACHE_NAME = 'app-shell-v3';
const PRECACHE_URLS = [
  '/',
  '/index.html',
  '/styles/main.css',
  '/scripts/app.js',
  '/icons/icon-192.png'
];

self.addEventListener('install', (event) => {
  // Die Installation gilt erst als abgeschlossen, wenn alles im Cache liegt
  event.waitUntil(
    (async () => {
      const cache = await caches.open(CACHE_NAME);
      await cache.addAll(PRECACHE_URLS);
      console.log(`[SW] ${PRECACHE_URLS.length} Dateien vorab gecacht`);
    })()
  );
});

[SW] 5 Dateien vorab gecacht

Wartephase überspringen mit oninstall und skipWaiting()

// sw.js – Variante mit der on-Property
self.oninstall = (event) => {
  console.log('Ereignistyp:', event.type, '| Instanz von InstallEvent:', event instanceof InstallEvent);
  event.waitUntil(
    (async () => {
      const cache = await caches.open('static-v4');
      await cache.add('/offline.html');
      // Neue Version sofort aktivieren statt auf das Schließen alter Tabs zu warten
      await self.skipWaiting();
    })()
  );
};

self.addEventListener('activate', (event) => {
  // Bestehende Seiten sofort übernehmen
  event.waitUntil(self.clients.claim());
});

Ereignistyp: install | Instanz von InstallEvent: true

Statische Routen mit addRoutes() (Chromium, experimentell)

// sw.js
self.addEventListener('install', (event) => {
  if (typeof event.addRoutes !== 'function') {
    console.log('Static Routing API nicht verfügbar');
    return;
  }
  event.waitUntil(
    event.addRoutes([
      {
        // Bilder direkt aus dem Netz laden, ohne den Service Worker zu starten
        condition: { urlPattern: new URLPattern({ pathname: '/images/*' }) },
        source: 'network'
      },
      {
        // Nur GET-Anfragen an /api/ gehen durch den fetch-Handler
        condition: { urlPattern: '/api/*', requestMethod: 'get' },
        source: 'fetch-event'
      }
    ])
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(fetch(event.request));
});

// Wichtig · Fallstricke

Ein abgelehntes Promise macht die Installation zunichte: Scheitert cache.addAll() an nur einer URL (etwa 404 oder Netzwerkfehler), wird der ganze neue Service Worker verworfen. Precache-Listen sollten deshalb kurz und verlässlich sein. Optionale Ressourcen besser außerhalb des waitUntil-Promises cachen.
waitUntil() muss synchron im Handler aufgerufen werden. Ein Aufruf nach einem await oder in einem setTimeout wirft einen InvalidStateError.
install läuft nur, wenn sich das Service-Worker-Skript byteweise ändert. Wer eine neue Version erzwingen will, sollte z. B. den Cache-Namen hochzählen.
self.skipWaiting() kann alte Seiten mit neuen Cache-Inhalten mischen. Das ist nur sinnvoll, wenn die Versionen zueinander kompatibel sind.
Die frühere Eigenschaft InstallEvent.activeWorker ist veraltet und aus den Browsern entfernt. Stattdessen self.registration.active verwenden.
addRoutes() ist experimentell und nur in Chromium (ab Version 123) verfügbar. Vor dem Aufruf per Feature-Erkennung prüfen. Die Methode darf nur während des install-Events aufgerufen werden.
Service Worker gibt es nur in sicheren Kontexten (HTTPS oder localhost). InstallEvent existiert ausschließlich im ServiceWorkerGlobalScope, nicht im Fenster-Kontext.

Siehe auch

CustomEvent GestureEvent InputEvent MessageEvent PopStateEvent