CKTIS / JavaScript
structuredClone(): copia profonda e trasferimento dei dati
structuredClone() copia le strutture di dati supportate, inclusi oggetti annidati e cicli. L’opzione transfer sposta le risorse invece di copiarle; non tutti i tipi di valore possono essere clonati.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
structuredClone(value)
structuredClone(value, { transfer: [transferable] })structuredClone(value, options) clona in modo sincrono i dati supportati. La copia conserva i cicli e i riferimenti ripetuti allo stesso oggetto. Tra i tipi supportati ci sono oggetti semplici, array, Date, Map, Set e ArrayBuffer.
Quando è consentito clonare un SharedArrayBuffer, il clone è un oggetto distinto, ma usa la stessa memoria dell’originale. Le modifiche scritte tramite uno dei due buffer sono visibili tramite l’altro anche senza usare l’opzione transfer.
Non è un metodo universale per copiare istanze di classi: i prototipi personalizzati, i descrittori delle proprietà e i campi privati non vengono conservati. Per gli oggetti ordinari copia le proprietà proprie enumerabili con chiavi stringa; la lettura dei getter può eseguire codice. Le funzioni e i valori Symbol incontrati durante la serializzazione causano una DOMException denominata DataCloneError.
L’opzione { transfer: [buffer] } trasferisce una risorsa ArrayBuffer invece di copiarne i byte. Il buffer originale viene scollegato e il suo byteLength diventa 0. L’elenco transfer non aggiunge risorse al risultato: devono essere raggiungibili da value perché il risultato possa accedervi.
Questa è un’API dello standard HTML, non una funzionalità introdotta in una specifica edizione di ECMAScript. La tabella di compatibilità dello standard indica Chrome 98+, Firefox 94+ e Safari 15.4+. Controlla typeof structuredClone === "function" nell’ambiente di destinazione; Node 24 in un repository non dimostra il supporto nei browser.
Esempi
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);Risultato
1 2 true true 0 4
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.