KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

structuredClone(): diep kopiëren en gegevens overdragen

structuredClone() kopieert ondersteunde gegevensstructuren, waaronder geneste objecten en cycli. De optie transfer verplaatst resources in plaats van ze te kopiëren; niet elk waardetype kan worden gekloond.

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

Syntax

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

structuredClone(value, options) kloont ondersteunde gegevens synchroon. Cycli en herhaalde verwijzingen naar hetzelfde object blijven binnen de kopie behouden. Ondersteunde typen zijn onder meer gewone objecten, arrays, Date, Map, Set en ArrayBuffer.

Als het klonen van een SharedArrayBuffer is toegestaan, is de kloon een afzonderlijk object, maar gebruikt hij hetzelfde geheugen als het origineel. Wijzigingen die via de ene buffer worden geschreven, zijn via de andere zichtbaar, ook zonder de optie transfer te gebruiken.

Het is geen universele manier om klasse-instanties te kopiëren: aangepaste prototypes, eigenschapsdescriptors en privévelden blijven niet behouden. Voor gewone objecten kopieert de functie eigen, opsombare eigenschappen met tekenreeksen als sleutels; het uitlezen van getters kan code uitvoeren. Functies en Symbol-waarden die tijdens het serialiseren worden aangetroffen, veroorzaken een DOMException met de naam DataCloneError.

De optie { transfer: [buffer] } draagt een ArrayBuffer-resource over in plaats van de bytes ervan te kopiëren. De oorspronkelijke buffer wordt losgekoppeld en de byteLength wordt 0. De lijst transfer voegt geen resources toe aan het resultaat: ze moeten bereikbaar zijn vanuit value, zodat het resultaat er toegang toe heeft.

Dit is een API uit de HTML-standaard, geen functie die in een bepaalde ECMAScript-editie is geïntroduceerd. De compatibiliteitstabel van de standaard vermeldt Chrome 98+, Firefox 94+ en Safari 15.4+. Controleer typeof structuredClone === "function" in de doelomgeving; Node 24 in een repository toont niet aan dat browsers dit ondersteunen.

Voorbeelden

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);

Resultaat

1 2
true true
0 4

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen