База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

structuredClone(): дълбоко копиране и прехвърляне на данни

structuredClone() копира поддържани структури от данни, включително вложени обекти и цикли. Опцията transfer премества ресурси, вместо да ги копира; не всеки тип стойност може да бъде клониран.

Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Синтаксис

structuredClone(value)
structuredClone(value, { transfer: [transferable] })

structuredClone(value, options) синхронно клонира поддържаните данни. В копието запазва циклите и повтарящите се препратки към един и същ обект. Поддържаните типове включват обикновени обекти, масиви, Date, Map, Set и ArrayBuffer.

Когато клонирането на SharedArrayBuffer е разрешено, клонингът е отделен обект, но използва същата памет като оригинала. Промените, записани чрез единия буфер, са видими чрез другия дори без използване на опцията transfer.

Това не е универсален начин за копиране на екземпляри на класове: персонализираните прототипи, дескрипторите на свойства и частните полета не се запазват. За обикновени обекти се копират собствените изброими свойства с низове за ключове; прочитането на getter-и може да изпълни код. Функции и стойности Symbol, срещнати по време на сериализацията, предизвикват DOMException с име DataCloneError.

Опцията { transfer: [buffer] } прехвърля ресурс ArrayBuffer, вместо да копира байтовете му. Оригиналният буфер се отделя и неговият byteLength става 0. Списъкът transfer не добавя ресурси към резултата: те трябва да са достижими от value, за да може резултатът да осигури достъп до тях.

Това е API от стандарта HTML, а не функция, въведена в конкретно издание на ECMAScript. Таблицата за съвместимост на стандарта посочва Chrome 98+, Firefox 94+ и Safari 15.4+. Проверете typeof structuredClone === "function" в целевата среда; Node 24 в хранилище не доказва поддръжка в браузърите.

Примери

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);

Резултат

1 2
true true
0 4

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници