XMLHttpRequestEventTarget: abort — Ereignis · JavaScript-Referenz

Signatur

xhr.addEventListener("abort", handler) / xhr.upload.addEventListener("abort", handler)

Beschreibung

Das abort-Ereignis gehört zum Interface XMLHttpRequestEventTarget. Es wird deshalb sowohl auf einem XMLHttpRequest-Objekt als auch auf dessen upload-Objekt (XMLHttpRequestUpload) ausgelöst. Der Auslöser ist fast immer ein Aufruf von xhr.abort(), solange die Anfrage noch läuft. Das Ereignis ist ein ProgressEvent, nicht abbrechbar (cancelable: false) und steigt nicht auf (bubbles: false).

Du registrierst einen Handler entweder mit addEventListener("abort", handler) oder über die Eigenschaft onabort. Mit addEventListener kannst du mehrere Handler anhängen und sie mit removeEventListener gezielt wieder entfernen. Eine Zuweisung an onabort ersetzt dagegen einen vorher zugewiesenen Handler.

Typische Einsatzfälle sind ein „Abbrechen“-Knopf bei großen Uploads, das Verwerfen veralteter Anfragen (etwa bei Suchvorschlägen während der Eingabe) und das Aufräumen der Oberfläche, also Ladeanzeigen ausblenden oder Schaltflächen wieder aktivieren. Beim Abbruch feuern die Ereignisse in dieser Reihenfolge: readystatechange (mit readyState 4), dann abort, dann loadend. Ein load- oder error-Ereignis gibt es in diesem Fall nicht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses: `"abort"`.
$handler Pflicht	(event: ProgressEvent) => void		Die Callback-Funktion. Sie bekommt ein `ProgressEvent` mit `loaded`, `total` und `lengthComputable`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein ProgressEvent, das den Stand zum Zeitpunkt des Abbruchs enthält (loaded/total).

Beispiele

Abbruch einer Anfrage mit addEventListener erkennen

const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/grosse-datei.json');

xhr.addEventListener('abort', (event) => {
  console.log(`Abgebrochen nach ${event.loaded} Bytes`);
});

xhr.addEventListener('loadend', () => {
  console.log('Anfrage beendet, readyState:', xhr.readyState, 'status:', xhr.status);
});

xhr.send();

// Nach 100 ms abbrechen
setTimeout(() => xhr.abort(), 100);

Abgebrochen nach 0 Bytes Anfrage beendet, readyState: 0 status: 0

Upload mit Abbrechen-Knopf (upload.onabort)

const input = document.querySelector('#datei');
const cancelBtn = document.querySelector('#abbrechen');
const statusEl = document.querySelector('#status');

input.addEventListener('change', () => {
  const file = input.files[0];
  if (!file) return;

  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/upload');

  xhr.upload.onprogress = (e) => {
    if (e.lengthComputable) {
      statusEl.textContent = `${Math.round((e.loaded / e.total) * 100)} %`;
    }
  };

  xhr.upload.onabort = () => {
    statusEl.textContent = 'Upload abgebrochen.';
    cancelBtn.disabled = true;
  };

  cancelBtn.disabled = false;
  cancelBtn.onclick = () => xhr.abort();

  const data = new FormData();
  data.append('datei', file);
  xhr.send(data);
});

Veraltete Suchanfragen verwerfen und Listener wieder entfernen

let current = null;

const onAbort = () => console.log('Alte Suchanfrage verworfen');

const search = (term) => {
  if (current) {
    current.abort(); // löst 'abort' auf der alten Anfrage aus
    current.removeEventListener('abort', onAbort);
  }

  const xhr = new XMLHttpRequest();
  xhr.open('GET', `/api/suche?q=${encodeURIComponent(term)}`);
  xhr.responseType = 'json';
  xhr.addEventListener('abort', onAbort);
  xhr.addEventListener('load', () => console.log('Treffer:', xhr.response));
  xhr.send();
  current = xhr;
};

search('ja');
search('java');
search('javascript');

Alte Suchanfrage verworfen Alte Suchanfrage verworfen Treffer: [...]

// Wichtig · Fallstricke

Kein Ereignis ohne laufende Anfrage: abort() löst das Ereignis nur aus, wenn die Anfrage schon gesendet wurde und noch nicht fertig ist. Bei readyState 0 (UNSENT) oder 4 (DONE) passiert nichts.
Nicht mit Timeout oder Netzwerkfehler verwechseln: Wird xhr.timeout überschritten, feuert timeout statt abort. Netzwerkfehler lösen error aus. Für Aufräumarbeiten, die in jedem Fall laufen sollen, eignet sich loadend am besten.
Zustand nach dem Abbruch: status ist danach 0, und readyState wird auf 0 zurückgesetzt, sobald die Ereignisse durch sind. Die Antwortdaten sind verworfen.
Upload-Listener rechtzeitig anhängen: Listener auf xhr.upload müssen vor send() registriert sein. Sonst feuern Upload-Ereignisse unter Umständen gar nicht, und das kann auch die CORS-Preflight-Logik beeinflussen.
Server bekommt den Abbruch nicht zwingend mit: Ein Abbruch auf Client-Seite beendet nur die Verbindung. Serverseitige Verarbeitung, die schon gestartet ist, läuft womöglich weiter.
Neuer Code: Mit fetch() übernehmen AbortController und AbortSignal (Ereignis abort auf dem Signal) diese Aufgabe. Die abgebrochene Anfrage lehnt das Promise dann mit einem AbortError ab.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern.

Siehe auch

XMLHttpRequest.prototype.abort() XMLHttpRequestEventTarget: loadend XMLHttpRequestEventTarget: error XMLHttpRequestEventTarget: timeout XMLHttpRequestEventTarget: progress ProgressEvent