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 March 2022.
Die structuredClone()
Methode der Window
Schnittstelle erstellt eine tiefe Kopie eines gegebenen Wertes unter Verwendung des structured clone algorithmus.
Die Methode ermöglicht es auch, transferierbare Objekte im ursprünglichen Wert zu übertragen statt sie zu klonen. Übertragene Objekte werden vom ursprünglichen Objekt getrennt und an das neue Objekt gebunden; sie sind im ursprünglichen Objekt nicht mehr zugänglich.
Syntax
structuredClone(value)
structuredClone(value, options)
Parameter
value
-
Das zu klonende Objekt. Dies kann jeder structured-clonebare Typ sein.
options
Optional-
Ein Objekt mit den folgenden Eigenschaften:
transfer
-
Ein Array von transferierbaren Objekten, die zum zurückgegebenen Objekt verschoben und nicht geklont werden.
Rückgabewert
Eine tiefe Kopie des ursprünglichen value
.
Ausnahmen
DataCloneError
DOMException
-
Wird ausgelöst, wenn ein Teil des Eingabewertes nicht serialisierbar ist.
Beschreibung
Diese Funktion kann verwendet werden, um JavaScript-Werte tief 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 it
const 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 values
console.assert(clone.itself === clone); // and the circular reference is preserved
Werte übertragen
Transferierbare Objekte können (nur) statt dupliziert zu werden im geklonten Objekt übertragen werden, indem die transfer
Eigenschaft des options
Parameters verwendet wird. Das Übertragen macht das ursprüngliche Objekt unbrauchbar.
Hinweis: Ein Szenario, in dem dies nützlich sein könnte, ist das asynchrone Validieren von Daten in einem Puffer, bevor sie gespeichert werden. Um zu vermeiden, dass der Puffer geändert wird, bevor die Daten gespeichert sind, können Sie den Puffer klonen und diese Daten validieren. Wenn Sie die Daten auch übertragen, schlagen alle Versuche, den ursprünglichen Puffer zu ändern, fehl, was einen versehentlichen Missbrauch verhindert.
Der folgende Code zeigt, wie ein Array geklont und seine zugrunde liegenden Ressourcen an das neue Objekt übertragen werden.
Nach der Rückkehr wird der ursprüngliche uInt8Array.buffer
gelöscht.
// 16MB = 1024 * 1024 * 16
const uInt8Array = Uint8Array.from({ length: 1024 * 1024 * 16 }, (v, i) => i);
const transferred = structuredClone(uInt8Array, {
transfer: [uInt8Array.buffer],
});
console.log(uInt8Array.byteLength); // 0
Sie können eine beliebige Anzahl von Objekten klonen und jede Teilmenge dieser Objekte übertragen.
Zum Beispiel würde der unten stehende Code arrayBuffer1
aus dem übergebenen Wert übertragen, aber nicht arrayBuffer2
.
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, das ein Array ist. Nach dem Klonen beeinflussen Änderungen an jedem Objekt das andere nicht.
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 einen ArrayBuffer
und klonen dann das Objekt, dessen Mitglied er ist, und übertragen den Puffer. Wir können den Puffer im geklonten Objekt verwenden, aber wenn wir versuchen, den originalen Puffer zu verwenden, werden wir eine Ausnahme erhalten.
// Create an ArrayBuffer with a size in bytes
const buffer1 = new ArrayBuffer(16);
const object1 = {
buffer: buffer1,
};
// Clone the object containing the buffer, and transfer it
const object2 = structuredClone(object1, { transfer: [buffer1] });
// Create an array from the cloned buffer
const int32View2 = new Int32Array(object2.buffer);
int32View2[0] = 42;
console.log(int32View2[0]);
// Creating an array from the original buffer throws a TypeError
const int32View1 = new Int32Array(object1.buffer);
Spezifikationen
Specification |
---|
HTML Standard # dom-structuredclone |
Browser-Kompatibilität
BCD tables only load in the browser