CKTIS / JavaScript
Algoritem strukturiranega kloniranja in prenos lastništva
structuredClone() kopira podprte podatkovne strukture ter v kopiji ohrani cikle in ponovljene reference. Možnost transfer prenese vire namesto njihovega kopiranja in odklopi izvirni ArrayBuffer.
Različica: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaksa
structuredClone(value)
structuredClone(value, { transfer: [buffer] })structuredClone(value) klonira podprte podatke. Algoritem si zapomni že obiskane objekte: v rezultatu ohrani cikle in skupne reference, vendar imajo klonirani objekti drugačno identiteto kot izvirniki. Ta algoritem uporabljata tudi postMessage() in IndexedDB.
Ločen objekt nima nujno lastnega pomnilnika. Pri kloniranju navadnega ArrayBuffer brez prenosa nastane neodvisna kopija njegovih bajtov, kot kaže primer. Kjer je kloniranje SharedArrayBuffer dovoljeno, je klon ločen objekt medpomnilnika, ki si z izvirnikom deli isti pomnilnik.
Med podprte tipe spadajo navadni objekti, polja, Map, Set, Date, ArrayBuffer in tipizirana polja. Funkcij, vozlišč DOM in vrednosti symbol ni mogoče klonirati; nepodprta vrednost v podatkih povzroči DataCloneError. Algoritem ne ohrani prilagojenih prototipnih verig, deskriptorjev lastnosti, getterjev/setterjev ali zasebnih elementov razredov. Zato ni univerzalen način kopiranja primerkov razredov.
structuredClone(value, { transfer: [buffer] }) prenese lastništvo vira, namesto da bi kopiral njegove bajte. Izvorni ArrayBuffer se odklopi: njegov byteLength je 0, obstoječi pogledi pa ne omogočajo več dostopa do podatkov. Uint8Array je mogoče klonirati, prenese pa se njegov buffer, ne sam pogled. ArrayBuffer na seznamu transfer se lahko odklopi, tudi če ni dosegljiv iz value. V tem primeru ga v vrnjeni kopiji ni. Za prenos ne potrebujete workerja.
To je gostiteljski API, določen v standardu HTML, ne pa funkcija določene izdaje ECMAScripta. MDN navaja široko podporo v brskalnikih od marca 2022; ciljno okolje preverite z typeof structuredClone === "function". Node 24 v repozitoriju ne dokazuje podpore v brskalniku. Primer primerja kopiranje s prenosom ter preverja ohranitev cikla in aliasa.
Referenčni identifikatorji, zajeti v tem geslu: Structured clone algorithm and transferable ownership.
Primeri
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);Rezultat
true true true 7 9 0 2 7 true true
Prikazana koda in navedeni rezultat sta bila preverjena v izoliranem okolju z metodo, zapisano v dokazilu o preverjanju te natančne različice.