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

CKTIS / JavaScript

Algoritmus strukturovaného klonování a přenos vlastnictví

structuredClone() kopíruje podporované datové struktury a v kopii zachovává cykly i opakované reference. Volba transfer přesouvá prostředky místo jejich kopírování a odpojí původní ArrayBuffer.

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: [buffer] })

structuredClone(value) klonuje podporovaná data. Algoritmus si pamatuje navštívené objekty: ve výsledku zachová cykly a sdílené reference, ale naklonované objekty mají jinou identitu než jejich originály. Tento algoritmus používají také postMessage() a IndexedDB.

Samostatný objekt nemusí mít vlastní paměť. Klonováním běžného ArrayBuffer bez přenosu vznikne nezávislá kopie jeho bajtů, jak ukazuje příklad. Tam, kde je klonování SharedArrayBuffer povoleno, je klon samostatným objektem bufferu, který s originálem sdílí stejnou paměť.

Mezi podporované typy patří běžné objekty, pole, Map, Set, Date, ArrayBuffer a typovaná pole. Funkce, uzly DOM a hodnoty symbol klonovat nelze; nepodporovaná hodnota v datech způsobí DataCloneError. Algoritmus nezachovává vlastní řetězce prototypů, deskriptory vlastností, gettery/settery ani soukromé prvky tříd. Nejde tedy o univerzální způsob kopírování instancí tříd.

structuredClone(value, { transfer: [buffer] }) převede vlastnictví prostředku místo kopírování jeho bajtů. Zdrojový ArrayBuffer se odpojí: jeho byteLength je 0 a stávající pohledy už neumožňují přístup k datům. Uint8Array lze klonovat, ale přenáší se jeho buffer, nikoli samotný pohled. ArrayBuffer uvedený v seznamu transfer se může odpojit, i když není dosažitelný z value. V takovém případě se ve vrácené kopii neobjeví. Přenos nevyžaduje worker.

Jde o hostitelské API definované standardem HTML, nikoli o funkci konkrétní edice ECMAScriptu. MDN uvádí širokou dostupnost v prohlížečích od března 2022; cílové prostředí ověřte pomocí typeof structuredClone === "function". Node 24 v repozitáři nedokazuje podporu v prohlížeči. Příklad porovnává kopírování s přenosem a ověřuje zachování cyklu a aliasu.

Referenční identifikátory zahrnuté v tomto hesle: Structured clone algorithm and transferable ownership.

Příklady

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

Výsledek

true true true
7 9
0 2
7 true true

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