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

CKTIS / JavaScript

structuredClone(): cópia profunda e transferência de dados

structuredClone() copia estruturas de dados suportadas, incluindo objetos aninhados e ciclos. A opção transfer move recursos em vez de os copiar; nem todos os tipos de valor podem ser clonados.

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, { transfer: [transferable] })

structuredClone(value, options) clona de forma síncrona os dados suportados. Preserva ciclos e referências repetidas ao mesmo objeto dentro da cópia. Os tipos suportados incluem objetos simples, arrays, Date, Map, Set e ArrayBuffer.

Quando é permitido clonar um SharedArrayBuffer, o clone é um objeto distinto, mas usa a mesma memória que o original. As alterações escritas através de um dos buffers podem ser observadas através do outro, mesmo sem usar a opção transfer.

Não é uma forma universal de copiar instâncias de classes: não preserva protótipos personalizados, descritores de propriedades nem campos privados. Para objetos comuns, copia propriedades próprias enumeráveis com chaves do tipo cadeia de caracteres; a leitura de getters pode executar código. As funções e os valores Symbol encontrados durante a serialização provocam uma DOMException denominada DataCloneError.

A opção { transfer: [buffer] } transfere um recurso ArrayBuffer em vez de copiar os respetivos bytes. O buffer original fica desligado e o seu byteLength passa a 0. A lista transfer não adiciona recursos ao resultado: estes têm de ser alcançáveis a partir de value para que o resultado lhes possa aceder.

Esta é uma API do padrão HTML, não uma funcionalidade introduzida numa edição específica de ECMAScript. A tabela de compatibilidade do padrão indica Chrome 98+, Firefox 94+ e Safari 15.4+. Verifique typeof structuredClone === "function" no ambiente de destino; Node 24 num repositório não comprova o suporte nos browsers.

Exemplos

const original = { items: [{ count: 1 }] };
original.self = original;
const copy = structuredClone(original);
copy.items[0].count = 2;
console.log(original.items[0].count, copy.items[0].count);
console.log(copy !== original, copy.self === copy);

const buffer = new ArrayBuffer(4);
const moved = structuredClone({ buffer }, { transfer: [buffer] });
console.log(buffer.byteLength, moved.buffer.byteLength);

Resultado

1 2
true true
0 4

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