Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

Źródła