ContentIndex.add() — Methode · JavaScript-Referenz

Signatur

ContentIndex.prototype.add(description)

Beschreibung

Mit add() teilt eine Progressive Web App dem Browser mit, dass ein bestimmter Inhalt offline verfügbar ist. Der Browser kann diese Einträge dann an einer eigenen Stelle zeigen, etwa im Bereich „Artikel für dich“ oder unter den Downloads in Chrome für Android. So findet der Nutzer zwischengespeicherte Inhalte auch ohne Netz.

Die Methode erreichst du über ServiceWorkerRegistration.index, also im Fenster über navigator.serviceWorker.ready oder direkt im Service Worker über self.registration.index. Rufe add() erst auf, nachdem der Inhalt wirklich im Cache liegt, zum Beispiel über die Cache API. Der Content Index speichert nur Metadaten und keine Daten.

Gibst du eine id an, die schon existiert, wird der alte Eintrag ersetzt. Löscht der Nutzer einen Eintrag in der Browser-Oberfläche, feuert im Service Worker das Event contentdelete. Dort solltest du den passenden Cache-Eintrag ebenfalls entfernen.

Parameter

Name	Typ	Default	Beschreibung
$description Pflicht	Object		Metadaten des Inhalts mit folgenden Feldern: `id` (`string`, Pflicht): eindeutige Kennung `title` (`string`, Pflicht): Titel für die Anzeige `description` (`string`, Pflicht): kurze Beschreibung `url` (`string`, Pflicht): Adresse, die beim Öffnen geladen wird; muss im Geltungsbereich (scope) des Service Workers liegen `category` (`string`, optional): `''` (Standard), `'homepage'`, `'article'`, `'video'` oder `'audio'` `icons` (`Array`, optional): Bild-Objekte mit `src` sowie optional `sizes`, `type` und `label`

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald der Eintrag registriert ist. Es wird mit einem TypeError abgelehnt, wenn Pflichtfelder fehlen oder leer sind, die url außerhalb des Service-Worker-Scopes liegt, ein Icon nicht geladen werden kann oder kein aktiver Service Worker vorhanden ist.

Beispiele

Artikel aus der Seite heraus registrieren

const saveArticleOffline = async (article) => {
  const registration = await navigator.serviceWorker.ready;

  // Feature-Erkennung
  if (!('index' in registration)) {
    console.log('Content Index wird nicht unterstützt.');
    return;
  }

  // Zuerst den Inhalt cachen ...
  const cache = await caches.open('articles-v1');
  await cache.add(article.url);

  // ... dann im Content Index eintragen
  try {
    await registration.index.add({
      id: `article-${article.id}`,
      title: article.title,
      description: article.teaser,
      category: 'article',
      url: article.url,
      icons: [{ src: '/icons/article-192.png', sizes: '192x192', type: 'image/png' }]
    });
    console.log('Artikel offline verfügbar:', article.title);
  } catch (err) {
    console.error('Registrierung fehlgeschlagen:', err.message);
  }
};

saveArticleOffline({
  id: 42,
  title: 'Service Worker verstehen',
  teaser: 'Grundlagen für Offline-Apps',
  url: '/artikel/service-worker-verstehen'
});

Artikel offline verfügbar: Service Worker verstehen

Im Service Worker nach periodischem Sync hinzufügen

// sw.js
self.addEventListener('periodicsync', (event) => {
  if (event.tag !== 'latest-news') return;

  event.waitUntil((async () => {
    const res = await fetch('/api/news/latest');
    const news = await res.json();
    const cache = await caches.open('news');

    for (const item of news) {
      await cache.add(item.url);
      await self.registration.index.add({
        id: item.id,
        title: item.title,
        description: item.summary,
        category: 'article',
        url: item.url
      });
    }
  })());
});

Aufräumen, wenn der Nutzer einen Eintrag löscht

// sw.js
self.addEventListener('contentdelete', (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open('articles-v1');
    const keys = await cache.keys();
    const id = event.id.replace('article-', '');
    for (const request of keys) {
      if (request.url.includes(`/artikel/${id}`)) {
        await cache.delete(request);
      }
    }
    console.log('Entfernt:', event.id);
  })());
});

Entfernt: article-42

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die API funktioniert in Chrome und Edge ab Version 84, sinnvoll vor allem auf Android. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'index' in registration, ob sie verfügbar ist.
Die API läuft nur in einem sicheren Kontext (HTTPS) und braucht einen aktiven Service Worker.
Die url muss im Scope des Service Workers liegen, sonst gibt es einen TypeError. Leere Werte für id, title, description oder url führen ebenfalls zu einem TypeError.
Trage nur Inhalte ein, die wirklich offline funktionieren. Ein Eintrag, der ohne Netz ins Leere führt, verschlechtert die Nutzererfahrung. Chrome kann solche Einträge außerdem ausblenden.
Icons werden beim Aufruf geladen. Eine Icon-Adresse, die nicht erreichbar ist, lässt das Promise scheitern.
Dieselbe id noch einmal zu verwenden, überschreibt den alten Eintrag. Das ist praktisch für Aktualisierungen.

Siehe auch

Cache ContentIndex.delete() ContentIndex.getAll() FontFaceSet.add() DOMTokenList.add()