structuredClone()

Tworzy głęboką kopię wartości, łącznie z zagnieżdżonymi obiektami, datami, Map i Set.

Zwraca: Głęboką kopię przekazanej wartości.
Zmienia oryginał: Nie

Na tej stronie

Przykład
Definicja i zastosowanie
Składnia
Parametry
Więcej przykładów
Obsługa przeglądarek
Dobre praktyki
Powiązane hasła

Przykład

JavaScript

const original = {
  name: 'Ania',
  progress: { html: 80, css: 40 },
  badges: ['Start']
}

const copy = structuredClone(original)
copy.progress.html = 100
copy.badges.push('Seria 7 dni')

console.log(original.progress.html, original.badges)
console.log(copy.progress.html, copy.badges)

Konsola

80 ['Start']

100 ['Start', 'Seria 7 dni']

Definicja i zastosowanie

Funkcja structuredClone() tworzy pełną, głęboką kopię podanej wartości. W przeciwieństwie do składni { ...obj } czy Object.assign(), które kopiują tylko pierwszy poziom, kopiuje też wszystkie zagnieżdżone obiekty i tablice. Zmiana kopii nie wpływa więc na oryginał.

Obsługuje więcej typów niż sztuczka JSON.parse(JSON.stringify(obj)): zachowuje daty jako obiekty Date, kopiuje Map, Set, wyrażenia regularne, tablice typowane i wartości undefined. Poprawnie radzi sobie też z obiektami, które odwołują się same do siebie.

Ma też ograniczenia. Nie da się sklonować funkcji ani elementów DOM (rzuca wtedy błąd DataCloneError), a instancje klas tracą swój prototyp i stają się zwykłymi obiektami z samymi danymi.

Składnia

structuredClone(value)
structuredClone(value, { transfer })

Parametry

value
dowolna wartość
Wartość do skopiowania: obiekt, tablica, data, Map, Set i inne.
options
opcjonalny obiekt
Obiekt z polem transfer, czyli listą obiektów (np. ArrayBuffer) do przeniesienia zamiast kopiowania.

Parametr	Typ	Opis
value	dowolna wartość	Wartość do skopiowania: obiekt, tablica, data, `Map`, `Set` i inne.
options	opcjonalny obiekt	Obiekt z polem `transfer`, czyli listą obiektów (np. `ArrayBuffer`) do przeniesienia zamiast kopiowania.

Więcej przykładów

Porównanie z kopią płytką

JavaScript

const course = { title: 'JS', stats: { students: 120 } }

const shallow = { ...course }
const deep = structuredClone(course)

shallow.stats.students = 200
console.log(course.stats.students)
console.log(deep.stats.students)

Konsola

200

120

Daty i Map zostają zachowane

JavaScript

const session = {
  startedAt: new Date(Date.UTC(2026, 8, 28, 10, 30)),
  answers: new Map([['q1', 'B']])
}

const viaJson = JSON.parse(JSON.stringify(session))
const cloned = structuredClone(session)

console.log(typeof viaJson.startedAt, viaJson.answers)
console.log(cloned.startedAt.getUTCHours(), cloned.answers.get('q1'))

Konsola

string {}

10 B

Funkcji nie da się sklonować

JavaScript

try {
  structuredClone({ name: 'Quiz', start() {} })
} catch (error) {
  console.log(error.name)
}

Konsola

DataCloneError

Obsługa przeglądarek

Szeroko dostępne · od 2022 roku

Działa we wszystkich nowoczesnych przeglądarkach, także na telefonach. Możesz używać bez obaw.

Chrome
Edge
Firefox
Safari

Dobre praktyki

Do kopiowania danych z zagnieżdżonymi obiektami używaj structuredClone() zamiast JSON.parse(JSON.stringify()).
Jeśli obiekt zawiera metody lub jest instancją klasy, sklonuj same dane albo napisz własną metodę kopiującą.
Gdy wystarczy kopia pierwszego poziomu, prostsza i szybsza jest składnia { ...obj }.

Powiązane hasła

Widzisz błąd albo brakuje przykładu? Napisz do nas.

Darmowy kursPrzećwicz JavaScript w kursie JavaScript i ReactZadania z podpowiedziami, edytor kodu i postępy zapisywane na bieżąco.Zobacz kurs