Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

structuredClone() : copie profonde et transfert de données

structuredClone() copie les structures de données prises en charge, y compris les objets imbriqués et les cycles. L’option transfer déplace les ressources au lieu de les copier ; tous les types de valeurs ne peuvent pas être clonés.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

structuredClone(value)
structuredClone(value, { transfer: [transferable] })

structuredClone(value, options) clone de façon synchrone les données prises en charge. La copie conserve les cycles et les références répétées vers un même objet. Les types pris en charge incluent les objets simples, les tableaux, Date, Map, Set et ArrayBuffer.

Lorsque le clonage d’un SharedArrayBuffer est autorisé, le clone est un objet distinct, mais il utilise la même mémoire que l’original. Les modifications écrites via l’un des tampons sont visibles via l’autre, même sans utiliser l’option transfer.

Ce n’est pas une méthode universelle pour copier des instances de classes : les prototypes personnalisés, les descripteurs de propriétés et les champs privés ne sont pas conservés. Pour les objets ordinaires, elle copie les propriétés propres énumérables dont les clés sont des chaînes de caractères ; la lecture d’une propriété dotée d’un accesseur en lecture (getter) peut exécuter du code. Les fonctions et les valeurs Symbol rencontrées pendant la sérialisation provoquent une DOMException nommée DataCloneError.

L’option { transfer: [buffer] } transfère une ressource ArrayBuffer au lieu d’en copier les octets. Le tampon d’origine est détaché et son byteLength passe à 0. La liste transfer n’ajoute pas de ressources au résultat : elles doivent être accessibles depuis value pour que le résultat puisse y accéder.

Il s’agit d’une API de la norme HTML, et non d’une fonctionnalité introduite dans une édition particulière d’ECMAScript. Le tableau de compatibilité de la norme indique Chrome 98+, Firefox 94+ et Safari 15.4+. Vérifiez typeof structuredClone === "function" dans l’environnement cible ; Node 24 dans un dépôt ne permet pas d’établir la prise en charge dans les navigateurs.

Exemples

const original = { items: [{ count: 1 }] };
original.self = original;
const copy = structuredClone(original);
copy.items[0].count = 2;
console.log(original.items[0].count, copy.items[0].count);
console.log(copy !== original, copy.self === copy);

const buffer = new ArrayBuffer(4);
const moved = structuredClone({ buffer }, { transfer: [buffer] });
console.log(buffer.byteLength, moved.buffer.byteLength);

Résultat

1 2
true true
0 4

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources