CKTIS / JavaScript
Algoritmus štruktúrovaného klonovania a prenos vlastníctva
structuredClone() kopíruje podporované dátové štruktúry a v kópii zachováva cykly aj opakované referencie. Voľba transfer presúva zdroje namiesto ich kopírovania a odpojí pôvodný ArrayBuffer.
Verzia: 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) klonuje podporované dáta. Algoritmus si zapamätá navštívené objekty: vo výsledku zachová cykly a zdieľané referencie, no naklonované objekty majú inú identitu než ich originály. Tento algoritmus používajú aj postMessage() a IndexedDB.
Samostatný objekt nemusí mať vlastnú pamäť. Pri klonovaní bežného ArrayBuffer bez prenosu vznikne nezávislá kópia jeho bajtov, ako ukazuje príklad. Ak je klonovanie SharedArrayBuffer povolené, klon je samostatný objekt buffera, ktorý s originálom zdieľa tú istú pamäť.
Medzi podporované typy patria bežné objekty, polia, Map, Set, Date, ArrayBuffer a typované polia. Funkcie, uzly DOM a hodnoty symbol sa nedajú klonovať; nepodporovaná hodnota v dátach spôsobí DataCloneError. Algoritmus nezachováva vlastné reťazce prototypov, deskriptory vlastností, gettery/settery ani súkromné prvky tried. Nie je teda univerzálnym spôsobom kopírovania inštancií tried.
structuredClone(value, { transfer: [buffer] }) prenáša vlastníctvo zdroja namiesto kopírovania jeho bajtov. Zdrojový ArrayBuffer sa odpojí: jeho byteLength je 0 a existujúce pohľady už neumožňujú prístup k dátam. Uint8Array možno klonovať, prenáša sa však jeho buffer, nie samotný pohľad. ArrayBuffer uvedený v zozname transfer sa môže odpojiť aj vtedy, keď nie je dosiahnuteľný z value. V takom prípade sa vo vrátenej kópii neobjaví. Prenos nevyžaduje worker.
Ide o hostiteľské API definované štandardom HTML, nie o funkciu konkrétneho vydania ECMAScriptu. MDN uvádza širokú dostupnosť v prehliadačoch od marca 2022; cieľové prostredie overte pomocou typeof structuredClone === "function". Node 24 v repozitári nedokazuje podporu v prehliadači. Príklad porovnáva kopírovanie s prenosom a kontroluje zachovanie cyklu a aliasu.
Referenčné identifikátory zahrnuté v tomto hesle: Structured clone algorithm and transferable ownership.
Prí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ýsledok
true true true 7 9 0 2 7 true true
Zobrazený kód a uvedený výsledok boli overené v izolovanom prostredí metódou zaznamenanou v dôkaze o overení tejto presnej verzie.