CKTIS / JavaScript
structuredClone(): hluboké kopírování a přenos dat
structuredClone() kopíruje podporované datové struktury včetně vnořených objektů a cyklů. Volba transfer přesouvá prostředky místo jejich kopírování; klonovat nelze každý typ hodnoty.
Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
structuredClone(value)
structuredClone(value, { transfer: [transferable] })structuredClone(value, options) synchronně klonuje podporovaná data. V kopii zachová cykly i opakované odkazy na stejný objekt. Mezi podporované typy patří běžné objekty, pole, Date, Map, Set a ArrayBuffer.
Pokud je klonování objektu SharedArrayBuffer povoleno, je klon samostatný objekt, který však používá stejnou paměť jako originál. Změny zapsané prostřednictvím jednoho bufferu lze pozorovat prostřednictvím druhého i bez použití volby transfer.
Nejde o univerzální způsob kopírování instancí tříd: vlastní prototypy, deskriptory vlastností ani privátní pole se nezachovají. U běžných objektů kopíruje vlastní výčtové vlastnosti s řetězcovými klíči; čtení getterů může spustit kód. Funkce a hodnoty Symbol, na které narazí během serializace, způsobí výjimku DOMException s názvem DataCloneError.
Volba { transfer: [buffer] } přenese prostředek ArrayBuffer místo kopírování jeho bajtů. Původní buffer se odpojí a jeho byteLength bude 0. Seznam transfer nepřidává prostředky do výsledku: musí být dosažitelné z value, aby k nim výsledek umožňoval přístup.
Jde o API standardu HTML, nikoli o funkci zavedenou v konkrétním vydání ECMAScriptu. Tabulka kompatibility standardu uvádí Chrome 98+, Firefox 94+ a Safari 15.4+. V cílovém prostředí ověřte typeof structuredClone === "function"; Node 24 v repozitáři nedokládá podporu v prohlížečích.
Příklady
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);Výsledek
1 2 true true 0 4
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.