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

CKTIS / JavaScript

JSON.stringify : d’une valeur JavaScript au texte JSON

JSON.stringify sérialise une valeur JavaScript en texte JSON ; un replacer facultatif sélectionne ou transforme les données et space règle l’indentation.

Version : ECMAScript 5 onward; well-formed lone-surrogate escaping from ECMAScript 2019; example target: Node.js 24.22.2

Syntaxe

JSON.stringify(value[, replacer[, space]])

JSON.stringify(value, replacer?, space?) renvoie une chaîne JSON, ou undefined si la valeur racine est undefined, une fonction ou un Symbol. Ces valeurs sont omises dans un objet mais deviennent null dans un tableau ; NaN et les infinis deviennent aussi null, tandis que -0 s’écrit 0. La méthode sérialise les propriétés propres énumérables à clé chaîne dans l’ordre défini de Object.keys ; les clés Symbol sont ignorées. La description des propriétés propres énumérables concerne la liste par défaut ; un tableau replacer lit les propriétés nommées avec Get et peut inclure une propriété héritée ou non énumérable.

Une méthode toJSON, si elle existe, s’exécute avant le replacer. Une fonction replacer reçoit (key, value), avec this égal au détenteur, et peut remplacer la valeur ou omettre une propriété en renvoyant undefined ; l’appel racine utilise la clé vide "". Un tableau replacer forme la liste autorisée des noms de propriétés d’objet. Un space numérique est limité à 10 espaces et un space chaîne à ses 10 premiers caractères. Pour un space chaîne, « 10 caractères » signifie exactement les 10 premières unités de code UTF-16.

Une référence cyclique lève TypeError. Un BigInt lève aussi TypeError sauf si la recherche ordinaire de propriété trouve un toJSON appelable ; la méthode peut provenir du prototype. Les exceptions d’un getter, de toJSON ou du replacer se propagent. L’ordre stable des propriétés ne rend pas la sortie canonique pour une signature cryptographique. La méthode est standard depuis ECMAScript 5 ; depuis ECMAScript 2019, les substituts Unicode isolés sont émis comme séquences \ud800–\udfff, produisant un Unicode bien formé.

Exemples

const value = {
  name: "Ada",
  missing: undefined,
  numbers: [1, NaN, Infinity, undefined],
  nested: { keep: true, secret: "hidden" },
};
console.log(JSON.stringify(value, (key, current) =>
  key === "secret" ? undefined : current,
));
console.log(JSON.stringify(undefined) === undefined);

try {
  JSON.stringify(1n);
} catch (error) {
  console.log(error instanceof TypeError);
}

const cycle = {};
cycle.self = cycle;
try {
  JSON.stringify(cycle);
} catch (error) {
  console.log(error instanceof TypeError);
}

Résultat

{"name":"Ada","numbers":[1,null,null,null],"nested":{"keep":true}}
true
true
true

Sources