BackgroundFetchRegistration.abort() — Methode · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.prototype.abort()

Beschreibung

Die Methode abort() des Interfaces BackgroundFetchRegistration bricht einen aktiven Hintergrundabruf ab. Den Abruf hat vorher BackgroundFetchManager.fetch() gestartet. Mit der Background Fetch API lädt der Browser große Ressourcen (Videos, Podcasts, Offline-Pakete) herunter, auch wenn der Tab oder die Seite schon geschlossen ist.

Brauchbar ist abort() vor allem für eine eigene „Download abbrechen“-Schaltfläche, für das Aufräumen veralteter Downloads oder wenn der Nutzer sich abmeldet. Nach dem Abbruch feuert im Service Worker das Event backgroundfetchabort. Die Eigenschaft failureReason der Registrierung hat dann den Wert "aborted".

Das zurückgegebene Promise wird mit true erfüllt, wenn der Abruf erfolgreich abgebrochen wurde. War der Abruf schon beendet oder bereits abgebrochen, wird es mit false erfüllt. Die Methode ist im Fensterkontext und im Service Worker verfügbar, solange man eine gültige Registrierung besitzt, etwa über BackgroundFetchManager.get(id).

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Wird mit true erfüllt, wenn der Hintergrundabruf abgebrochen wurde, sonst mit false (zum Beispiel wenn er schon abgeschlossen war).

Beispiele

Laufenden Download per Schaltfläche abbrechen

// Im Fensterkontext: Abbruch-Button für einen Offline-Download
const cancelButton = document.querySelector('#cancel-download');

cancelButton.addEventListener('click', async () => {
  const swReg = await navigator.serviceWorker.ready;
  const bgFetch = await swReg.backgroundFetch.get('podcast-folge-42');

  if (!bgFetch) {
    console.log('Kein aktiver Download gefunden.');
    return;
  }

  const aborted = await bgFetch.abort();
  console.log(aborted ? 'Download abgebrochen.' : 'Download war bereits beendet.');
});

Download abgebrochen.

Download starten und nach Zeitlimit abbrechen

const startDownload = async () => {
  const swReg = await navigator.serviceWorker.ready;

  if (!('backgroundFetch' in swReg)) {
    console.warn('Background Fetch wird nicht unterstützt.');
    return;
  }

  const bgFetch = await swReg.backgroundFetch.fetch(
    'film-offline',
    ['/media/film.mp4'],
    { title: 'Film wird heruntergeladen', downloadTotal: 500 * 1024 * 1024 }
  );

  // Nach 10 Minuten abbrechen, falls noch nicht fertig
  setTimeout(async () => {
    if (bgFetch.result === '') {
      const ok = await bgFetch.abort();
      console.log('Abgebrochen:', ok);
    }
  }, 10 * 60 * 1000);
};

startDownload();

Abgebrochen: true

Alle laufenden Hintergrundabrufe abbrechen und im Service Worker reagieren

// Fensterkontext: z. B. beim Logout alle Downloads beenden
const abortAllFetches = async () => {
  const swReg = await navigator.serviceWorker.ready;
  const ids = await swReg.backgroundFetch.getIds();

  const results = await Promise.all(
    ids.map(async (id) => {
      const reg = await swReg.backgroundFetch.get(id);
      return reg ? reg.abort() : false;
    })
  );
  console.log(`${results.filter(Boolean).length} von ${ids.length} abgebrochen`);
};

// service-worker.js: auf den Abbruch reagieren
self.addEventListener('backgroundfetchabort', (event) => {
  console.log('Abgebrochen:', event.registration.id, event.registration.failureReason);
});

2 von 2 abgebrochen Abgebrochen: film-offline aborted

// Wichtig · Fallstricke

Kompatibilität: Die Background Fetch API ist experimentell und steckt nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Vor der Nutzung mit 'backgroundFetch' in registration prüfen.
Die API braucht einen sicheren Kontext (HTTPS) und einen aktiven Service Worker.
Ein Rückgabewert von false ist kein Fehler. Er bedeutet nur, dass der Abruf schon beendet war. Bei result gleich "success" oder "failure" hat abort() keine Wirkung.
Bereits heruntergeladene Teilantworten werden nach dem Abbruch verworfen. Im Handler von backgroundfetchabort kann man nicht mehr auf die Antworten zugreifen, matchAll() ist dann nicht sinnvoll nutzbar.
Brechen Nutzer den Download über die Download-Oberfläche des Browsers ab, feuert ebenfalls backgroundfetchabort, obwohl abort() nie aufgerufen wurde.

Siehe auch

BackgroundFetchRegistration.match() BackgroundFetchRegistration.matchAll() BackgroundFetchManager.get() BackgroundFetchManager.fetch() BackgroundFetchManager.getIds()