Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

AbortController — cancelar operações fetch

AbortController comunica um pedido de cancelamento através de `signal`. `fetch` cria um objeto `Request` antes de verificar o sinal. Se a criação falhar, a promise é rejeitada com o erro correspondente (por exemplo, um `TypeError` se o URL for inválido), mesmo que o sinal já esteja cancelado. Se `fetch` detetar o cancelamento enquanto a promise ainda estiver pendente, rejeita-a com o motivo do cancelamento. Se a promise já tiver sido cumprida com um objeto `Response`, o cancelamento não altera o seu estado, mas pode interromper a leitura em curso do corpo da resposta.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const controller = new AbortController();
const signal = controller.signal;
controller.abort(reason);
fetch(input, { signal });

AbortController é uma API Web, não faz parte de uma edição específica de ECMAScript. AbortController.signal designa a propriedade de instância controller.signal; AbortController.abort designa o método de instância controller.abort(reason), não um método estático.

Passa signal a fetch. abort(reason) sinaliza o cancelamento; o motivo predefinido é uma DOMException com o nome AbortError. Não é possível repor um sinal: uma nova operação que necessite de cancelamento independente precisa de um novo controlador.

Se fetch conseguir criar um objeto Request e detetar que o sinal já está cancelado, rejeita a promise com o motivo do cancelamento. O cancelamento também pode interromper a leitura do corpo da resposta, mas não desfaz o trabalho já realizado pelo servidor. Trata a rejeição em vez de ignorar os erros.

O exemplo cancela antes de fetch, eliminando corridas temporais. Verifica a disponibilidade no navegador de destino; a presença de Node 24 no repositório não comprova o suporte dos navegadores.

Exemplos

(async () => {
  const controller = new AbortController();
  const reason = new Error("Cancelled");
  controller.abort(reason);

  try {
    await fetch("data:text/plain,hello", {
      signal: controller.signal
    });
    console.log("unexpected success");
  } catch (error) {
    console.log(controller.signal.aborted);
    console.log(error === reason);
  }
})();

Resultado

true
true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes