Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

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.

Zdroje