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

CKTIS / JavaScript

Алгоритъм за структурирано клониране и прехвърляне на собственост

structuredClone() копира поддържаните структури от данни, като запазва циклите и повтарящите се препратки в копието. Опцията transfer прехвърля ресурси вместо да ги копира и отделя първоначалния ArrayBuffer.

Версия: 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: [buffer] })

structuredClone(value) клонира поддържаните данни. Алгоритъмът запомня вече посетените обекти: запазва циклите и споделените препратки в резултата, но клонираните обекти имат различна идентичност от оригиналите. Този алгоритъм се използва и от postMessage() и IndexedDB.

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

Сред поддържаните типове са обикновени обекти, масиви, Map, Set, Date, ArrayBuffer и типизирани масиви. Функции, DOM възли и стойности symbol не могат да бъдат клонирани; неподдържана стойност в данните причинява DataCloneError. Алгоритъмът не запазва персонализирани прототипни вериги, дескриптори на свойства, getters/setters или частни елементи на класове. Затова той не е универсален начин за копиране на екземпляри на класове.

structuredClone(value, { transfer: [buffer] }) прехвърля собствеността върху ресурс, вместо да копира байтовете му. Изходният ArrayBuffer се отделя: неговият byteLength е 0, а съществуващите изгледи вече не осигуряват достъп до данните. Uint8Array може да бъде клониран, но се прехвърля неговият buffer, а не самият изглед. ArrayBuffer, включен в списъка transfer, може да бъде отделен дори ако не е достижим от value. В такъв случай той няма да присъства във върнатото копие. За прехвърлянето не е необходим worker.

Това е API на средата, дефиниран в HTML стандарта, а не функция на конкретно издание на ECMAScript. MDN посочва широка наличност в браузърите от март 2022 г.; проверете целевата среда с typeof structuredClone === "function". Наличието на Node 24 в хранилище не доказва поддръжка в браузърите. Примерът сравнява копиране с прехвърляне и проверява дали цикълът се запазва и дали двете препратки в резултата сочат към един и същ обект.

Референтни идентификатори, обхванати в тази статия: Structured clone algorithm and transferable ownership.

Примери

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

Резултат

true true true
7 9
0 2
7 true true

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

Източници