CKTIS / JavaScript
structuredClone(): głębokie kopiowanie i transfer danych
structuredClone() kopiuje obsługiwane struktury danych wraz z zagnieżdżonymi obiektami i cyklami. Opcja transfer przenosi zasoby zamiast je kopiować; nie każdy typ wartości można sklonować.
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: [transferable] })structuredClone(value, options) synchronicznie klonuje obsługiwane dane. Zachowuje cykle i wielokrotne odwołania do tego samego obiektu wewnątrz kopii. Obsługuje między innymi zwykłe obiekty, tablice, Date, Map, Set i ArrayBuffer.
Jeśli klonowanie SharedArrayBuffer jest dozwolone, klon jest odrębnym obiektem, ale korzysta z tej samej pamięci co oryginał. Zmiany zapisane za pośrednictwem jednego bufora można odczytać za pośrednictwem drugiego nawet bez użycia opcji transfer.
Nie jest uniwersalnym sposobem kopiowania instancji klas: nie zachowuje niestandardowych prototypów, deskryptorów właściwości ani prywatnych pól. Dla zwykłych obiektów kopiuje własne wyliczalne właściwości o kluczach tekstowych; odczyt getterów może wykonać kod. Funkcje i wartości Symbol napotkane podczas serializacji powodują wyjątek DOMException o nazwie DataCloneError.
Opcja { transfer: [buffer] } przenosi zasób ArrayBuffer, zamiast kopiować jego bajty. Oryginalny bufor zostaje odłączony i ma byteLength równe 0. Lista transfer nie dodaje zasobów do wyniku: muszą być osiągalne z value, aby wynik zapewniał do nich dostęp.
To API standardu HTML, nie funkcja wprowadzona w konkretnej edycji ECMAScript. Tabela zgodności w standardzie wskazuje Chrome 98+, Firefox 94+ i Safari 15.4+. Sprawdź typeof structuredClone === "function" w docelowym środowisku; Node 24 w repozytorium nie potwierdza obsługi w przeglądarce.
Przykłady
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);Wynik
1 2 true true 0 4
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.