structuredClone()

Crée une copie profonde d’une valeur, y compris les objets imbriqués, les dates, les Map et les Set.

Renvoie: Une copie profonde de la valeur donnée.
Modifie l’original: Non

Sur cette page

Exemple
Définition et utilisation
Syntaxe
Paramètres
Plus d’exemples
Compatibilité des navigateurs
Bonnes pratiques
Entrées associées

Exemple

JavaScript

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

const copy = structuredClone(original)
copy.progress.html = 100
copy.badges.push('Série de 7 jours')

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

Console

80 ['Start']

100 ['Start', 'Série de 7 jours']

Définition et utilisation

La fonction structuredClone() crée une copie complète et profonde de la valeur donnée. Contrairement à la syntaxe { ...obj } ou à Object.assign(), qui ne copient que le premier niveau, elle copie aussi tous les objets et tableaux imbriqués. Modifier la copie n’affecte donc pas l’original.

Elle gère plus de types que l’astuce JSON.parse(JSON.stringify(obj)) : elle conserve les dates comme objets Date, et copie Map, Set, les expressions régulières, les tableaux typés et les valeurs undefined. Elle gère aussi correctement les objets qui se référencent eux-mêmes.

Elle a aussi des limites. Impossible de cloner des fonctions ou des éléments du DOM (cela déclenche une DataCloneError), et les instances de classes perdent leur prototype pour devenir de simples objets ne contenant que les données.

Syntaxe

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

Paramètres

value
n’importe quelle valeur
La valeur à copier : un objet, un tableau, une date, une Map, un Set, etc.
options
objet optionnel
Un objet avec un champ transfer, une liste d’objets (par ex. ArrayBuffer) à déplacer plutôt qu’à copier.

Paramètre	Type	Description
value	n’importe quelle valeur	La valeur à copier : un objet, un tableau, une date, une `Map`, un `Set`, etc.
options	objet optionnel	Un objet avec un champ `transfer`, une liste d’objets (par ex. `ArrayBuffer`) à déplacer plutôt qu’à copier.

Plus d’exemples

Copie superficielle contre copie profonde

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)

Console

200

120

Les dates et les Map sont conservées

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

Console

string {}

10 B

Impossible de cloner une fonction

JavaScript

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

Console

DataCloneError

Compatibilité des navigateurs

Largement disponible · depuis 2022

Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.

Chrome
Edge
Firefox
Safari

Bonnes pratiques

Pour copier des données avec des objets imbriqués, utilisez structuredClone() plutôt que JSON.parse(JSON.stringify()).
Si un objet contient des méthodes ou est une instance de classe, clonez seulement les données, ou écrivez votre propre méthode de copie.
Quand une copie du premier niveau suffit, la syntaxe { ...obj } est plus simple et plus rapide.

Entrées associées

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.

Leçons gratuitesPratiquez JavaScript dans le cours JavaScript et ReactDes exercices avec indices, un éditeur de code et une progression enregistrée au fur et à mesure.Voir le cours