CKTIS / JavaScript
Structured-Clone-Algorithmus und übertragbares Eigentum
structuredClone() kopiert unterstützte Datenstrukturen und erhält dabei Zyklen und wiederholte Referenzen innerhalb der Kopie. Mit der Option transfer werden Ressourcen verschoben statt kopiert; der ursprüngliche ArrayBuffer wird dadurch abgetrennt.
Version: 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: [buffer] })structuredClone(value) klont unterstützte Daten. Der Algorithmus merkt sich bereits besuchte Objekte: Zyklen und gemeinsame Referenzen innerhalb des Ergebnisses bleiben erhalten, die geklonten Objekte haben jedoch eine andere Identität als die Originale. Auch postMessage() und IndexedDB verwenden diesen Algorithmus.
Ein eigenständiges Objekt hat nicht zwangsläufig eigenen Speicher. Wird ein gewöhnlicher ArrayBuffer ohne Übertragung geklont, entsteht eine unabhängige Kopie seiner Bytes, wie das Beispiel zeigt. Wo das Klonen eines SharedArrayBuffer zulässig ist, entsteht ein eigenständiges Pufferobjekt, das denselben Speicher wie das Original nutzt.
Zu den unterstützten Typen gehören einfache Objekte, Arrays, Map, Set, Date, ArrayBuffer und typisierte Arrays. Funktionen, DOM-Knoten und symbol-Werte können nicht geklont werden; ein nicht unterstützter Wert in den Daten verursacht DataCloneError. Der Algorithmus erhält keine benutzerdefinierten Prototypketten, Property-Deskriptoren, Getter/Setter oder privaten Klassenelemente. Er ist daher keine universelle Methode, um Klasseninstanzen zu kopieren.
structuredClone(value, { transfer: [buffer] }) überträgt das Eigentum an einer Ressource, statt deren Bytes zu kopieren. Der ursprüngliche ArrayBuffer wird abgetrennt: Sein byteLength ist 0, und vorhandene Views bieten keinen Zugriff mehr auf die Daten. Ein Uint8Array kann geklont werden, übertragen wird jedoch sein buffer, nicht der View selbst. Ein ArrayBuffer in der transfer-Liste kann auch dann abgetrennt werden, wenn er von value aus nicht erreichbar ist. In diesem Fall ist er in der zurückgegebenen Kopie nicht enthalten. Für die Übertragung ist kein Worker erforderlich.
Dies ist eine Host-API, die im HTML-Standard definiert ist, und kein Merkmal einer bestimmten ECMAScript-Ausgabe. MDN gibt an, dass sie seit März 2022 in Browsern breit verfügbar ist; prüfe die Zielumgebung mit typeof structuredClone === "function". Node 24 in einem Repository belegt keine Browserunterstützung. Das Beispiel vergleicht Kopieren mit Übertragen und prüft, ob ein Zyklus und ein Alias erhalten bleiben.
In diesem Eintrag behandelte Referenzbezeichner: Structured clone algorithm and transferable ownership.
Beispiele
const bytes = new Uint8Array([7, 8]);
const original = { bytes, alias: bytes };
original.self = original;
const copy = structuredClone(original);
copy.bytes[0] = 9;
console.log(copy !== original, copy.self === copy, copy.bytes === copy.alias);
console.log(original.bytes[0], copy.bytes[0]);
const moved = structuredClone(original, { transfer: [bytes.buffer] });
console.log(bytes.buffer.byteLength, moved.bytes.byteLength);
console.log(moved.bytes[0], moved.self === moved, moved.bytes === moved.alias);Ergebnis
true true true 7 9 0 2 7 true true
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.