Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten.Erfahre mehr über dieses Experiment.
Window: structuredClone() Methode
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since März 2022.
DiestructuredClone()-Methode derWindow-Schnittstelle erstellt einetiefe Kopie eines gegebenen Werts unter Verwendung desstructured clone algorithmus.
Die Methode ermöglicht auch, dassübertragbare Objekte im ursprünglichen Wertübertragen anstatt geklont werden. Übertragene Objekte werden vom ursprünglichen Objekt getrennt und dem neuen Objekt zugeordnet; sie sind im ursprünglichen Objekt nicht mehr zugänglich.
Syntax
structuredClone(value)structuredClone(value, options)Parameter
valueDas zu klonende Objekt. Dies kann jederstrukturklonbare Typ sein.
optionsOptionalEin Objekt mit den folgenden Eigenschaften:
transferEin Array vonübertragbaren Objekten, die anstatt geklont, in das zurückgegebene Objekt verschoben werden.
Rückgabewert
Einetiefe Kopie des ursprünglichenvalue.
Ausnahmen
DataCloneErrorDOMExceptionWird ausgelöst, wenn ein Teil des Eingabewertes nicht serialisierbar ist.
Beschreibung
Diese Funktion kann verwendet werden, um JavaScript-Wertetief zu kopieren.Sie unterstützt auch zirkuläre Referenzen, wie unten gezeigt:
// Create an object with a value and a circular reference to itself.const original = { name: "MDN" };original.itself = original;// Clone itconst clone = structuredClone(original);console.assert(clone !== original); // the objects are not the same (not same identity)console.assert(clone.name === "MDN"); // they do have the same valuesconsole.assert(clone.itself === clone); // and the circular reference is preservedÜbertragen von Werten
Übertragbare Objekte (nur) können anstelle der Duplizierung im geklonten Objekt übertragen werden, indem dietransfer-Eigenschaft desoptions-Parameters verwendet wird. Das Übertragen macht das ursprüngliche Objekt unbrauchbar.
Hinweis:Ein Szenario, in dem dies nützlich sein könnte, ist, wenn Daten in einem Puffer asynchron validiert werden, bevor sie gespeichert werden. Um zu vermeiden, dass der Puffer verändert wird, bevor die Daten gespeichert werden, können Sie den Puffer klonen und diese Daten validieren. Wenn Sie die Daten auchübertragen, werden alle Versuche, den ursprünglichen Puffer zu ändern, fehlschlagen, was einen versehentlichen Missbrauch verhindert.
Der folgende Code zeigt, wie man ein Array klont und dessen zugrunde liegende Ressourcen in das neue Objekt überträgt. Nach der Rückkehr wird der ursprünglicheuInt8Array.buffer geleert.
// 16MB = 1024 * 1024 * 16const uInt8Array = Uint8Array.from({ length: 1024 * 1024 * 16 }, (v, i) => i);const transferred = structuredClone(uInt8Array, { transfer: [uInt8Array.buffer],});console.log(uInt8Array.byteLength); // 0Sie können beliebig viele Objekte klonen und einen Teil dieser Objekte übertragen. Zum Beispiel würde der untenstehende CodearrayBuffer1 aus dem übergebenen Wert übertragen, jedoch nichtarrayBuffer2.
const transferred = structuredClone( { x: { y: { z: arrayBuffer1, w: arrayBuffer2 } } }, { transfer: [arrayBuffer1] },);Beispiele
Klonen eines Objekts
In diesem Beispiel klonen wir ein Objekt mit einem Mitglied, welches ein Array ist. Nach dem Klonen beeinflussen Änderungen an jedem Objekt nicht das andere Objekt.
const mushrooms1 = { amanita: ["muscaria", "virosa"],};const mushrooms2 = structuredClone(mushrooms1);mushrooms2.amanita.push("pantherina");mushrooms1.amanita.pop();console.log(mushrooms2.amanita); // ["muscaria", "virosa", "pantherina"]console.log(mushrooms1.amanita); // ["muscaria"]Übertragen eines Objekts
In diesem Beispiel erstellen wir einArrayBuffer und klonen dann das Objekt, dessen Mitglied es ist, wobei der Puffer übertragen wird. Wir können den Puffer im geklonten Objekt verwenden, aber wenn wir versuchen, den ursprünglichen Puffer zu verwenden, erhalten wir eine Ausnahme.
// Create an ArrayBuffer with a size in bytesconst buffer = new ArrayBuffer(16);const object1 = { buffer,};// Clone the object containing the buffer, and transfer itconst object2 = structuredClone(object1, { transfer: [buffer] });// Create an array from the cloned bufferconst int32View2 = new Int32Array(object2.buffer);int32View2[0] = 42;console.log(int32View2[0]);// Creating an array from the original buffer throws a TypeErrorconst int32View1 = new Int32Array(object1.buffer);Spezifikationen
| Specification |
|---|
| HTML # dom-structuredclone |