JSON.stringify

La méthode JSON.stringify() convertit une valeur JavaScript en chaîne JSON. Optionnellement, elle peut remplacer des valeurs ou spécifier les propriétés à inclure si un tableau de propriétés a été fourni.

Syntaxe

JSON.stringify( valeur[, remplaçant [, espace]])

Paramètres

valeur

La valeur à convertir en chaîne JSON.

remplaçant Facultatif

Une fonction qui modifie le processus de transformation ou un tableau de chaînes de caractères et de nombres qui sont utilisés comme liste blanche pour sélectionner/filtrer les propriétés de l'objet à inclure dans la chaîne JSON. Si cette valeur est nulle ou n'est pas fournie, toutes les propriétés de l'objet seront inclues dans la chaîne résultante.

espace Facultatif

Un objet String ou Number qui est utilisé pour insérer des blancs dans la chaîne JSON produite afin de faciliter la lisibilité. Si cet argument est un nombre, il indiquera le nombre d'espaces à utiliser pour l'indentation (la valeur est ramenée à 10 si elle dépasse 10). Si l'argument est une chaîne, les 10 premiers caractères (ou la chaîne si elle est plus courte) seront utilisés pour les blancs. Si le paramètre n'est pas fourni (ou s'il est nul), aucun blanc ne sera utilisé.

Valeur de retour

Une chaîne de caractères JSON qui représente la valeur indiquée.

Description

La fonction JSON.stringify() convertit un objet en JSON :

• L'ordre des propriétés des objets qui ne sont pas des tableaux n'est pas garanti. Par la suite, ne pas supposer que cet ordre soit respecté.
• Les objets Boolean, Number et String sont convertis en leur valeur primitive correspondante, en accord avec la sémantique traditionnelle.
• Si undefined, une fonction ou un symbole est rencontré lors de la conversion , il est soit omis ( quand il se trouve dans un objet ) ou ramené à null ( quand il se trouve dans un tableau). JSON.stringify() peut également renvoyer undefined lorsqu'il reçoit des valeurs « brutes » qui ne sont pas objectifiées comme par exemple JSON.stringify(function(){}) ou JSON.stringify(undefined).
• Toutes les propriétés liées aux symboles seront complètement ignorées , même lorsque la fonction remplaçant est utilisée.
• Les propriétés qui ne sont pas énumérables seront ignorées.

JSON.stringify({});                        // '{}'
JSON.stringify(true);                      // 'true'
JSON.stringify("toto");                    // '"toto"'
JSON.stringify([1, "false", false]);       // '[1,"false",false]'
JSON.stringify({ x: 5 });                  // '{"x":5}'

JSON.stringify(new Date(2006, 0, 2, 15, 4, 5));
// '"2006-01-02T23:04:05.000Z"'

// Exemples
JSON.stringify({x: 5, y: 6});              
// '{"x":5,"y":6}' or '{"y":6,"x":5}'
JSON.stringify([new Number(1), new String("false"), new Boolean(false)]); 
// '[1,"false",false]'

// Symboles
JSON.stringify({x: undefined, y: Object, z: Symbol("")}); 
// '{}'
JSON.stringify({[Symbol("toto")]: "toto"});                 
// '{}'
JSON.stringify({[Symbol.for("toto")]: "toto"}, [Symbol.for("toto")]);
// '{}'
JSON.stringify({[Symbol.for("toto")]: "toto"}, function (k, v) {
  if (typeof k === "symbol"){
    return "a symbol";
  }
});
// '{}'
JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] });
// '{"x":[10,null,null,null]}'

// Propriétés non énumérables
JSON.stringify(Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

L'argument remplaçant

L'argument remplaçant est une fonction ou un tableau. Si c'est une fonction, elle prend deux paramètres : un clé et la valeur qui est traitée pour être convertie en chaîne. L'objet dans lequel la clé a été trouvée sera fourni comme paramètre this pour la fonction. Cette fonction est d'abord appelée avec une clé vide représentant l'objet à transformer puis elle est appelée sur chaque propriété de l'objet ou du tableau à transformer en chaîne. Cette fonction renvoie la valeur à ajouter à la chaîne JSON :

• Si la valeur renvoyée est un nombre (Number), la chaîne correspondante au nombre sera utilisée comme valeur à ajouter à la chaîne pour représenter la valeur de la propriété traitée.
• Si la valeur renvoyée est une chaîne de caractères (String), cette chaîne sera utilisée pour représenter la valeur de la propriété dans la chaîne JSON.
• Si la valeur renvoyée est un Boolean, "true" ou "false" sera utilisé pour représenter la valeur de la propriété et sera ajouté à la chaîne JSON.
• Si la valeur renvoyée est un autre objet, cet objet sera, de façon récursive, transformé en une chaîne JSON en appelant la fonction remplaçant sur chaque propriété sauf si l'objet est une fonction auquel cas, rien n'est ajouté à la chaîne JSON.
• Si la valeur renvoyée est undefined undefined, la propriété ne sera pas incluse dans la chaîne JSON.

Exemple avec une fonction

function remplaçant(clé, valeur) {
  if (typeof valeur === "string") {
    return undefined;
  }
  return valeur;
}

var toto = {fondation: "Mozilla", modèle: "boîte", semaine: 45, transport: "bus", mois: 7};
console.log(JSON.stringify(toto, remplaçant)); // {"semaine":45, "mois":7}

Exemple avec un tableau

Si remplaçant est un tableau, les valeurs du tableau indiquent les propriétés de l'objet à inclure dans la chaîne JSON.

JSON.stringify(toto, ['semaine', 'mois']);  
// '{"semaine":45,"mois":7}', on ne garde que "semaines" et "mois"

L'argument espace

L'argument espace est utilisé pour contrôler les espacements utilisés dans la chaîne finale. Si c'est un nombre, les différents niveaux d'indentation auront autant d'espaces qu'indiqué grâce à ce paramètre (jusqu'à 10). Si c'est une chaîne, les dix premiers caractères (ou la chaîne complète si elle est plus courte)

JSON.stringify({ a: 2 }, null, ' ');
// '{
//  "a": 2
// }'

Dans l'exemple suivant on utilise la tabulation pour rendre lisible le résultat :

JSON.stringify({ uno: 1, dos: 2 }, null, '\t');
// renverra
// '{
//     "uno": 1,
//     "dos": 2
// }'

La fonction toJSON()

Pour personnaliser la valeur d'un objet lors de sa conversion en JSON, on peut surcharger la méthode toJSON : la valeur retournée par cette méthode toJSON sera alors utilisée. Ainsi :

var obj ={
	toto: 'toto',
	toJSON :function () {
		return 'truc';
		}
	}
JSON.stringify(obj); // '"truc"'
JSON.stringify({x: obj}); // '{"x":"truc"}'

Gestion des terminateurs de ligne

JSON n'est pas un sous-ensemble strict de JavaScript. En effet, en JSON, deux terminateurs de ligne (le caractère de séparation de ligne et le caractère de séparation de paragraphe) n'ont pas besoin d'être échappés alors qu'ils doivent l'être en JavaScript. Ainsi, si le JSON doit être évalué ou utilisé avec JSONP, on pourra utiliser la fonction utilitaire suivante :

function jsFriendlyJSONStringify (s) {
    return JSON.stringify(s).
        replace(/\u2028/g, '\\u2028').
        replace(/\u2029/g, '\\u2029');
}

var s = {
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029)
};

// dans Firefox, console.log enlève les échappements
// des caractères Unicode, on utilise donc alert :(
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

Utiliser JSON.stringify avec localStorage

Dans le cas où on souhaite enregistrer un objet créé par l'utilisateur afin de le restorer plus tard (y compris après que le navigateur ait été fermé), on peut utiliser JSON.stringify.

// On crée un objet pour l'exemple
var session = {
    'screens' : [],
    'state' : true
};
session.screens.push({"name":"screenA", "width":450, "height":250});
session.screens.push({"name":"screenB", "width":650, "height":350});
session.screens.push({"name":"screenC", "width":750, "height":120});
session.screens.push({"name":"screenD", "width":250, "height":60});
session.screens.push({"name":"screenE", "width":390, "height":120});
session.screens.push({"name":"screenF", "width":1240, "height":650});

// On convertit l'objet en une chaîne JSON
// et on enregistre cette valeur avec le nom 'session'
localStorage.setItem('session', JSON.stringify(session));

// Ici, on reconvertit la chaîne en un objet 
// JSON.stringify and saved in localStorage in JSON object again
var sessionRestaurée = JSON.parse(localStorage.getItem('session'));

// La variable sessionRestaurée contient désormais l'objet précédent
// qui avait été sauvegardé dans localStorage
console.log(sessionRestaurée);

Spécifications

Compatibilité des navigateurs

Voir aussi

• JSON.parse()