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

CKTIS / JavaScript

DOMException DataCloneError — échec du clonage des données

DataCloneError est le nom d’une DOMException indiquant que des données ne peuvent pas être clonées. Découvrez une cause courante avec structuredClone(), comment reconnaître cette erreur et en quoi une valeur non prise en charge diffère d’une référence circulaire prise en charge.

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, options)
error.name === "DataCloneError"

DataCloneError DOMException désigne un objet DOMException dont le name vaut "DataCloneError", et non un constructeur DataCloneError distinct. Son ancien code est 25 (DATA_CLONE_ERR) ; identifiez l’erreur avec name, et non avec le code numérique obsolète.

structuredClone() déclenche cette exception de façon synchrone si une partie quelconque des données à cloner ne peut pas être sérialisée selon l’algorithme de clonage structuré. Les fonctions et les nœuds DOM ne sont pas pris en charge, y compris à l’intérieur d’un objet ordinaire. Les références circulaires, à elles seules, ne provoquent pas d’échec : l’algorithme peut les préserver. Cet algorithme sert également à envoyer des données avec postMessage() entre Workers et à stocker des valeurs dans IndexedDB.

Dans l’exemple, task contient une fonction ; le premier clonage déclenche donc une exception. Le bloc catch ne traite que l’erreur attendue et relance toute autre erreur. Le deuxième clonage ne sélectionne que des données. Transmettez des valeurs prises en charge plutôt que des fonctions ou des nœuds DOM. Ne faites pas dépendre le test du texte complet de message.

Il s’agit d’un mécanisme de Web API, et non d’une fonctionnalité associée à une édition particulière d’ECMAScript. MDN indique que structuredClone() est disponible dans les principaux navigateurs depuis mars 2022 ; vérifiez la compatibilité avec votre environnement cible. La présence de Node 24 dans un dépôt ne prouve pas que l’API est prise en charge dans le navigateur.

Exemples

const value = { count: 3, task: () => 42 };

try {
  structuredClone(value);
} catch (error) {
  if (!(error instanceof DOMException) || error.name !== "DataCloneError") {
    throw error;
  }
  console.log(error.name);
}

const copy = structuredClone({ count: value.count });
console.log(copy.count);

Résultat

DataCloneError
3

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