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

CKTIS / JavaScript

Algorithme de clonage structuré et transfert de propriété

structuredClone() copie les structures de données prises en charge tout en préservant les cycles et les références répétées dans la copie. L’option transfer déplace les ressources au lieu de les copier et détache l’ArrayBuffer d’origine.

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: [buffer] })

structuredClone(value) clone les données prises en charge. L’algorithme mémorise les objets déjà visités : il préserve les cycles et les références partagées dans le résultat, mais les objets clonés ont une identité différente de celle des objets d’origine. postMessage() et IndexedDB utilisent également cet algorithme.

Un objet distinct n’a pas nécessairement sa propre mémoire. Le clonage sans transfert d’un ArrayBuffer ordinaire produit une copie indépendante de ses octets, comme le montre l’exemple. Lorsque le clonage d’un SharedArrayBuffer est autorisé, le clone est un objet tampon distinct qui partage la même mémoire que l’original.

Parmi les types pris en charge figurent les objets simples, les tableaux, Map, Set, Date, ArrayBuffer et les tableaux typés. Les fonctions, les nœuds DOM et les valeurs symbol ne peuvent pas être clonés ; une valeur non prise en charge dans les données provoque DataCloneError. L’algorithme ne préserve pas les chaînes de prototypes personnalisées, les descripteurs de propriétés, les getters/setters ni les éléments privés des classes. Il ne constitue donc pas une méthode universelle pour copier des instances de classes.

structuredClone(value, { transfer: [buffer] }) transfère la propriété d’une ressource au lieu d’en copier les octets. L’ArrayBuffer source est détaché : son byteLength vaut 0, et les vues existantes ne permettent plus d’accéder aux données. Un Uint8Array peut être cloné, mais c’est son buffer qui est transféré, pas la vue elle-même. Un ArrayBuffer figurant dans la liste transfer peut être détaché même s’il n’est pas accessible depuis value. Dans ce cas, il ne figure pas dans la copie renvoyée. Le transfert ne nécessite pas de worker.

Il s’agit d’une API hôte définie par la norme HTML, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. MDN indique une large disponibilité dans les navigateurs depuis mars 2022 ; vérifiez l’environnement cible avec typeof structuredClone === "function". La présence de Node 24 dans un dépôt ne prouve pas la prise en charge par les navigateurs. L’exemple compare la copie et le transfert, et vérifie la préservation d’un cycle et d’un alias.

Identifiants de référence couverts par cette entrée : Structured clone algorithm and transferable ownership.

Exemples

const bytes = new Uint8Array([7, 8]);
const original = { bytes, alias: bytes };
original.self = original;

const copy = structuredClone(original);
copy.bytes[0] = 9;
console.log(copy !== original, copy.self === copy, copy.bytes === copy.alias);
console.log(original.bytes[0], copy.bytes[0]);

const moved = structuredClone(original, { transfer: [bytes.buffer] });
console.log(bytes.buffer.byteLength, moved.bytes.byteLength);
console.log(moved.bytes[0], moved.self === moved, moved.bytes === moved.alias);

Résultat

true true true
7 9
0 2
7 true true

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