CKTIS / JavaScript
Algorytm klonowania strukturalnego i przenoszenie własności
structuredClone() kopiuje obsługiwane struktury danych, zachowując cykle i powtarzające się referencje wewnątrz kopii. Opcja transfer przenosi zasoby zamiast je kopiować i odłącza oryginalny ArrayBuffer.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
structuredClone(value)
structuredClone(value, { transfer: [buffer] })structuredClone(value) klonuje obsługiwane dane. Algorytm zapamiętuje odwiedzone obiekty: zachowuje cykle oraz wspólne referencje wewnątrz wyniku, lecz sklonowane obiekty mają inną tożsamość niż oryginały. Korzystają z niego również postMessage() i IndexedDB.
Odrębna tożsamość obiektu nie oznacza, że klon zawsze ma niezależną pamięć. Zwykły ArrayBuffer klonowany bez transferu otrzymuje niezależną kopię bajtów, co pokazuje przykład. Tam, gdzie klonowanie SharedArrayBuffer jest dozwolone, klon jest odrębnym obiektem bufora, ale korzysta z tej samej pamięci co oryginał.
Obsługiwane są m.in. zwykłe obiekty, tablice, Map, Set, Date, ArrayBuffer i tablice typowane. Funkcje, węzły DOM i wartości typu symbol nie podlegają klonowaniu; nieobsługiwana wartość w danych powoduje DataCloneError. Algorytm nie zachowuje własnego łańcucha prototypów, deskryptorów właściwości, getterów/setterów ani prywatnych elementów klas. Nie jest więc uniwersalnym sposobem kopiowania instancji klas.
structuredClone(value, { transfer: [buffer] }) przenosi własność zasobu zamiast kopiować jego bajty. Źródłowy ArrayBuffer zostaje odłączony: jego byteLength wynosi 0, a dotychczasowe widoki nie dają już dostępu do danych. Uint8Array można klonować, ale przenosi się jego buffer, nie sam widok. ArrayBuffer umieszczony na liście transfer może zostać odłączony nawet wtedy, gdy nie jest osiągalny z value. W takim przypadku nie pojawi się w zwróconej kopii. Transfer nie wymaga workera.
To API środowiska wykonawczego, określone w standardzie HTML, a nie funkcja konkretnej edycji ECMAScript. MDN podaje szeroką dostępność przeglądarkową od marca 2022; sprawdź docelowe środowisko przez typeof structuredClone === "function". Node 24 w repozytorium nie dowodzi obsługi w przeglądarce. Przykład porównuje kopiowanie z transferem i sprawdza zachowanie cyklu oraz aliasu.
Identyfikatory objęte tym wpisem: Structured clone algorithm and transferable ownership.
Przykłady
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);Wynik
true true true 7 9 0 2 7 true true
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.