Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

structuredClone(): copia profunda y transferencia de datos

structuredClone() copia estructuras de datos compatibles, incluidos objetos anidados y ciclos. La opción transfer mueve recursos en lugar de copiarlos; no se pueden clonar todos los tipos de valores.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

structuredClone(value)
structuredClone(value, { transfer: [transferable] })

structuredClone(value, options) clona de forma síncrona los datos compatibles. Conserva los ciclos y las referencias repetidas al mismo objeto dentro de la copia. Entre los tipos compatibles se incluyen objetos simples, arrays, Date, Map, Set y ArrayBuffer.

Cuando se permite clonar un SharedArrayBuffer, el clon es un objeto distinto, pero utiliza la misma memoria que el original. Los cambios escritos a través de uno de los búferes se pueden observar a través del otro, incluso sin usar la opción transfer.

No es una forma universal de copiar instancias de clases: no conserva prototipos personalizados, descriptores de propiedades ni campos privados. En los objetos ordinarios, copia las propiedades propias enumerables con claves de tipo cadena; leer getters puede ejecutar código. Las funciones y los valores Symbol encontrados durante la serialización provocan una DOMException llamada DataCloneError.

La opción { transfer: [buffer] } transfiere un recurso ArrayBuffer en lugar de copiar sus bytes. El búfer original queda desvinculado y su byteLength pasa a ser 0. La lista transfer no añade recursos al resultado: deben ser accesibles desde value para que el resultado permita acceder a ellos.

Esta es una API del estándar HTML, no una función introducida en una edición concreta de ECMAScript. La tabla de compatibilidad del estándar indica Chrome 98+, Firefox 94+ y Safari 15.4+. Comprueba typeof structuredClone === "function" en el entorno de destino; Node 24 en un repositorio no demuestra que haya compatibilidad en el navegador.

Ejemplos

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes