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

CKTIS / JavaScript

DOMException DataCloneError — erro ao clonar dados

DataCloneError é o nome de uma DOMException que indica que não é possível clonar os dados. Aprende uma causa comum com structuredClone(), como reconhecer o erro e porque é que um valor não suportado é diferente de uma referência circular suportada.

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

structuredClone(value)
structuredClone(value, options)
error.name === "DataCloneError"

DataCloneError DOMException designa um objeto DOMException cujo name é "DataCloneError", não um construtor DataCloneError distinto. O código histórico é 25 (DATA_CLONE_ERR); identifica o erro através de name, não do código numérico obsoleto.

structuredClone() lança esta exceção de forma síncrona quando qualquer parte dos dados a clonar não pode ser serializada pelo algoritmo de clonagem estruturada. As funções e os nós DOM não são suportados, nem mesmo dentro de um objeto normal. As referências circulares, por si só, não causam uma falha: o algoritmo consegue preservá-las. Este algoritmo também é utilizado para enviar dados através de postMessage() entre Workers e para guardar valores no IndexedDB.

No exemplo, task contém uma função, pelo que a primeira clonagem lança uma exceção. O bloco catch trata apenas o erro esperado e volta a lançar qualquer outro. A segunda clonagem seleciona apenas dados. Passa valores suportados em vez de funções ou nós DOM. Não faças o teste depender do texto completo de message.

Este é um mecanismo de Web API, não uma funcionalidade atribuída a uma edição específica do ECMAScript. A MDN indica que structuredClone() está disponível nos principais browsers desde março de 2022; verifica a compatibilidade com o ambiente de destino. A presença de Node 24 num repositório não prova que a API seja suportada no browser.

Exemplos

const value = { count: 3, task: () => 42 };

try {
  structuredClone(value);
} catch (error) {
  if (!(error instanceof DOMException) || error.name !== "DataCloneError") {
    throw error;
  }
  console.log(error.name);
}

const copy = structuredClone({ count: value.count });
console.log(copy.count);

Resultado

DataCloneError
3

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