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