AbortSignal

Instanz-Eigenschaften

Erbt auch Eigenschaften von seiner Elternschnittstelle, EventTarget.

AbortSignal.aborted Schreibgeschtzt

Ein Boolean, welches anzeigt, ob die Anfrage(n), mit denen das Signal kommuniziert, abgebrochen ist/sind (true) oder nicht (false).

AbortSignal.reason Schreibgeschtzt

Ein JavaScript-Wert, der den Abbruchgrund bereitstellt, sobald das Signal abgebrochen wurde.

Statische Methoden

Erbt auch Methoden von seiner Elternschnittstelle, EventTarget.

AbortSignal.abort()

Gibt eine AbortSignal Instanz zurck, die bereits als abgebrochen gesetzt ist.

AbortSignal.any()

Gibt ein AbortSignal zurck, das abbricht, wenn eines der gegebenen Abbruchsignale abbricht.

AbortSignal.timeout()

Gibt eine AbortSignal Instanz zurck, die nach einer bestimmten Zeit automatisch abbricht.

Instanz-Methoden

Erbt auch Methoden von seiner Elternschnittstelle, EventTarget.

AbortSignal.throwIfAborted()

Wirft den Abbruch-reason des Signals, wenn das Signal abgebrochen wurde; ansonsten tut es nichts.

Ereignisse

Erbt auch Ereignisse von seiner Elternschnittstelle, EventTarget.

Hren Sie auf dieses Ereignis mit addEventListener() oder indem Sie einen Ereignis-Listener auf die oneventname-Eigenschaft dieser Schnittstelle setzen.

abort

Wird aufgerufen, wenn die asynchronen Operationen, mit denen das Signal kommuniziert, abgebrochen sind. Auch ber die onabort-Eigenschaft verfgbar.

Beispiele

Abbrechen einer Fetch-Operation mit einem expliziten Signal

Das folgende Snippet zeigt, wie wir ein Signal verwenden knnen, um das Herunterladen eines Videos mithilfe der Fetch API abzubrechen.

Zuerst definieren wir eine Variable fr unseren AbortController.

Vor jeder Fetch-Anfrage erstellen wir einen neuen Controller mit dem AbortController()-Konstruktor und holen uns dann eine Referenz zu seinem zugehrigen AbortSignal-Objekt mit der AbortController.signal-Eigenschaft.

Wenn die Fetch-Anfrage initiiert wird, bergeben wir das AbortSignal als Option im Optionsobjekt der Anfrage (das { signal } unten). Dies assoziiert das Signal und den Controller mit der Fetch-Anfrage und ermglicht es uns, sie abzubrechen, indem wir AbortController.abort() aufrufen, wie unten im zweiten Event-Listener zu sehen.

Wenn abort() aufgerufen wird, wird das fetch()-Versprechen mit einem DOMException namens AbortError abgelehnt.

let controller;
const url = "video.mp4";

const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");

downloadBtn.addEventListener("click", fetchVideo);

abortBtn.addEventListener("click", () => {
  if (controller) {
    controller.abort();
    console.log("Download aborted");
  }
});

async function fetchVideo() {
  controller = new AbortController();
  const signal = controller.signal;

  try {
    const response = await fetch(url, { signal });
    console.log("Download complete", response);
    // process response further
  } catch (err) {
    console.error(`Download error: ${err.message}`);
  }
}

Wenn die Anfrage nach dem Erfllen des fetch()-Aufrufs, aber bevor der Antwortkrper gelesen wurde, abgebrochen wird, wird der Versuch, den Antwortkrper zu lesen, mit einer AbortError-Ausnahme abgelehnt.

async function get() {
  const controller = new AbortController();
  const request = new Request("https://example.org/get", {
    signal: controller.signal,
  });

  const response = await fetch(request);
  controller.abort();
  // The next line will throw `AbortError`
  const text = await response.text();
  console.log(text);
}

Sie knnen ein voll funktionsfhiges Beispiel auf GitHub finden; Sie knnen es auch live sehen.

Abbrechen einer Fetch-Operation mit einem Timeout

Wenn Sie die Operation bei einem Timeout abbrechen mssen, knnen Sie die statische Methode AbortSignal.timeout() verwenden. Dies gibt ein AbortSignal zurck, das automatisch nach einer festgelegten Anzahl von Millisekunden abbricht.

Der folgende Codeausschnitt zeigt, wie Sie entweder das Herunterladen einer Datei erfolgreich abschlieen oder einen Timeout-Fehler nach 5 Sekunden behandeln wrden. Beachten Sie, dass, wenn ein Timeout eintritt, das fetch()-Versprechen mit einem TimeoutError DOMException abgelehnt wird. Dies erlaubt es dem Code, zwischen Timeouts (fr die wahrscheinlich eine Benachrichtigung des Nutzers erforderlich ist) und Benutzerabbrchen zu unterscheiden.

const url = "video.mp4";

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
  const result = await res.blob();
  // 
} catch (err) {
  if (err.name === "TimeoutError") {
    console.error("Timeout: It took more than 5 seconds to get the result!");
  } else if (err.name === "AbortError") {
    console.error(
      "Fetch aborted by user action (browser stop button, closing tab, etc.)",
    );
  } else {
    // A network error, or some other problem.
    console.error(`Error: type: ${err.name}, message: ${err.message}`);
  }
}

Abbrechen eines Fetch mit Timeout oder explizitem Abbruch

Wenn Sie von mehreren Signalen her abbrechen mchten, knnen Sie AbortSignal.any() verwenden, um sie in ein einziges Signal zu kombinieren. Das folgende Beispiel zeigt dies mit fetch:

try {
  const controller = new AbortController();
  const timeoutSignal = AbortSignal.timeout(5000);
  const res = await fetch(url, {
    // This will abort the fetch when either signal is aborted
    signal: AbortSignal.any([controller.signal, timeoutSignal]),
  });
  const body = await res.json();
} catch (e) {
  if (e.name === "AbortError") {
    // Notify the user of abort.
  } else if (e.name === "TimeoutError") {
    // Notify the user of timeout
  } else {
    // A network error, or some other problem.
    console.log(`Type: ${e.name}, Message: ${e.message}`);
  }
}

Implementierung einer abbrechbaren API

Eine API, die das Abbrechen untersttzen muss, kann ein AbortSignal-Objekt akzeptieren und seinen Status verwenden, um das Abbruchsignal-Handling bei Bedarf auszulsen.

Eine auf Promise basierende API sollte auf das Abbruchsignal reagieren, indem sie ein nicht erflltes Versprechen mit dem AbortSignal-Abbruch-reason ablehnt. Zum Beispiel, betrachten Sie das folgende myCoolPromiseAPI, das ein Signal nimmt und ein Versprechen zurckgibt. Das Versprechen wird sofort abgelehnt, wenn das Signal bereits abgebrochen ist oder wenn das Abbruchereignis erkannt wird. Andernfalls wird es normal abgeschlossen und dann das Versprechen erfllt.

function myCoolPromiseAPI(/* , */ { signal }) {
  return new Promise((resolve, reject) => {
    // If the signal is already aborted, immediately throw in order to reject the promise.
    signal.throwIfAborted();

    // Perform the main purpose of the API
    // Call resolve(result) when done.

    // Watch for 'abort' signals
    // Passing `once: true` ensures the Promise can be garbage collected after abort is called
    signal.addEventListener(
      "abort",
      () => {
        // Stop the main operation
        // Reject the promise with the abort reason.
        reject(signal.reason);
      },
      { once: true },
    );
  });
}

Die API knnte dann wie gezeigt verwendet werden. Beachten Sie, dass AbortController.abort() aufgerufen wird, um die Operation abzubrechen.

const controller = new AbortController();
const signal = controller.signal;

startSpinner();

myCoolPromiseAPI({ /* , */ signal })
  .then((result) => {})
  .catch((err) => {
    if (err.name === "AbortError") return;
    showUserErrorMessage();
  })
  .then(() => stopSpinner());

controller.abort();

APIs, die keine Versprechen zurckgeben, knnten in hnlicher Weise reagieren. In einigen Fllen kann es sinnvoll sein, das Signal zu absorbieren.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Fetch API
• Abbrechbares Fetch von Jake Archibald