CKTIS / JavaScript
AbortController et AbortSignal : demander une annulation et lire son état
Transmettez `controller.signal` à une opération qui prend en charge l’annulation, demandez-la avec `controller.abort()` et lisez `signal.aborted` pour connaître l’état du signal, pas le résultat de l’opération.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
const controller = new AbortController();
const signal = controller.signal;
const aborted = signal.aborted;
// Two call forms; choose one for the first abort:
controller.abort();
controller.abort(reason);Créez un contrôleur avec new AbortController() et conservez-le dans le code qui décide quand annuler. La propriété d’instance en lecture seule controller.signal renvoie toujours le même objet AbortSignal pour ce contrôleur. Transmettez-le à une API qui l’accepte, par exemple fetch(url, { signal }). Plusieurs opérations peuvent partager un signal si elles doivent être annulées ensemble.
signal.aborted est une propriété booléenne en lecture seule, pas une méthode. Elle vaut initialement false. Le premier appel à controller.abort() ou à controller.abort(reason) fait passer l’état du signal à true de façon synchrone et déclenche l’évènement abort avant de renvoyer undefined. signal.reason contient la valeur fournie ; si l’argument est omis ou vaut undefined, la propriété contient une DOMException nommée AbortError.
Les appels suivants ne remplacent pas le motif et ne déclenchent pas d’autre évènement. Le signal ne peut pas être réinitialisé : créez un nouveau contrôleur pour un nouveau cycle d’annulation. La méthode statique AbortSignal.abort() crée, elle, un nouveau signal déjà annulé au lieu de modifier le signal d’un contrôleur existant.
L’annulation est coopérative. aborted === true décrit le signal : cela ne confirme pas l’arrêt d’une opération et n’annule pas le travail déjà effectué. Dans votre propre API à promesses, vérifiez le signal avant de commencer, gérez un éventuel évènement abort ultérieur, rejetez toute promesse encore en attente avec signal.reason et retirez l’écouteur en cas de fin normale. Ces API relèvent de la plateforme web, pas d’ECMAScript 2024 ; vérifiez leur disponibilité dans l’environnement cible.
Exemples
{
const controller = new AbortController();
const signal = controller.signal;
console.log(`before: ${signal.aborted}`);
signal.addEventListener("abort", () => {
console.log(`event: ${signal.aborted}`);
});
controller.abort("superseded");
controller.abort("ignored");
console.log(`after: ${signal.aborted}, ${signal.reason}`);
}Résultat
before: false event: true after: true, superseded
La ligne `event: true` montre que l’état a déjà changé lorsque l’écouteur s’exécute. Le deuxième appel ne déclenche pas d’autre évènement et ne remplace pas le motif `superseded`.
Leçons associées
- JavaScript · Leçon 4 · Avancé · Version : 4