CKTIS / JavaScript
AbortController e AbortSignal: pedir o cancelamento e consultar o estado
Passa `controller.signal` a uma operação que aceite cancelamento, pede-o com `controller.abort()` e lê `signal.aborted` para consultar o estado do sinal, não o resultado da operação.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
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);Cria um controlador com new AbortController() e mantém-no no código que decide quando cancelar. A propriedade de instância só de leitura controller.signal devolve sempre o mesmo objeto AbortSignal para esse controlador. Passa-o a uma API que o aceite, por exemplo com fetch(url, { signal }). Várias operações podem partilhar um sinal se tiverem de ser canceladas em conjunto.
signal.aborted é uma propriedade booleana só de leitura, não um método. Começa com o valor false. A primeira chamada a controller.abort() ou controller.abort(reason) muda o estado do sinal para true de forma síncrona e dispara o evento abort antes de devolver undefined. signal.reason contém o valor fornecido; se o argumento for omitido ou for undefined, contém uma DOMException com o nome AbortError.
As chamadas seguintes não substituem o motivo nem disparam outro evento. Não é possível repor o estado inicial do sinal: cria um controlador novo para um novo ciclo de cancelamento. O método estático AbortSignal.abort() é diferente: cria um sinal novo, já cancelado, em vez de alterar o sinal de um controlador existente.
O cancelamento é cooperativo. aborted === true descreve o sinal: não confirma que a operação parou nem desfaz trabalho já concluído. Numa API tua baseada em promessas, verifica o sinal antes de começar, trata um eventual evento abort posterior, rejeita com signal.reason qualquer promessa ainda pendente e remove o ouvinte no fim normal da operação. Estas API são da plataforma web, não de ECMAScript 2024; verifica se são suportadas no ambiente de execução de destino.
Exemplos
{
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}`);
}Resultado
before: false event: true after: true, superseded
A linha `event: true` mostra que o estado já mudou quando o ouvinte é executado. A segunda chamada não dispara outro evento nem substitui o motivo `superseded`.
Lições relacionadas
- JavaScript · Lição 4 · Avançado · Versão: 4