AbortSignal

Instanz-Eigenschaften

Erbt auch Eigenschaften von seiner Elternschnittstelle, EventTarget.

AbortSignal.aborted Schreibgeschützt

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

AbortSignal.reason Schreibgeschützt

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 zurück, die bereits als abgebrochen gesetzt ist.

AbortSignal.any()

Gibt ein AbortSignal zurück, das abbricht, wenn eines der gegebenen Abbruchsignale abbricht.

AbortSignal.timeout()

Gibt eine AbortSignal Instanz zurück, 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.

Hören 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 verfügbar.

Beispiele

Abbrechen einer Fetch-Operation mit einem expliziten Signal

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

Zuerst definieren wir eine Variable für unseren AbortController.

Vor jeder Fetch-Anfrage erstellen wir einen neuen Controller mit dem AbortController()-Konstruktor und holen uns dann eine Referenz zu seinem zugehörigen 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 ermöglicht 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 Erfüllen des fetch()-Aufrufs, aber bevor der Antwortkörper gelesen wurde, abgebrochen wird, wird der Versuch, den Antwortkörper 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 können ein voll funktionsfähiges Beispiel auf GitHub finden; Sie können es auch live sehen.

Abbrechen einer Fetch-Operation mit einem Timeout

Wenn Sie die Operation bei einem Timeout abbrechen müssen, können Sie die statische Methode AbortSignal.timeout() verwenden. Dies gibt ein AbortSignal zurück, das automatisch nach einer festgelegten Anzahl von Millisekunden abbricht.

Der folgende Codeausschnitt zeigt, wie Sie entweder das Herunterladen einer Datei erfolgreich abschließen oder einen Timeout-Fehler nach 5 Sekunden behandeln würden. Beachten Sie, dass, wenn ein Timeout eintritt, das fetch()-Versprechen mit einem TimeoutError DOMException abgelehnt wird. Dies erlaubt es dem Code, zwischen Timeouts (für die wahrscheinlich eine Benachrichtigung des Nutzers erforderlich ist) und Benutzerabbrüchen 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 möchten, können 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 unterstützen muss, kann ein AbortSignal-Objekt akzeptieren und seinen Status verwenden, um das Abbruchsignal-Handling bei Bedarf auszulösen.

Eine auf Promise basierende API sollte auf das Abbruchsignal reagieren, indem sie ein nicht erfülltes Versprechen mit dem AbortSignal-Abbruch-reason ablehnt. Zum Beispiel, betrachten Sie das folgende myCoolPromiseAPI, das ein Signal nimmt und ein Versprechen zurückgibt. 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 erfüllt.

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 könnte 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 zurückgeben, könnten in ähnlicher Weise reagieren. In einigen Fällen kann es sinnvoll sein, das Signal zu absorbieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Fetch API
• Abbrechbares Fetch von Jake Archibald