JSON : mthode statique stringify()

Exemple interactif

console.log(JSON.stringify({ x: 5, y: 6 }));
// Rsultat attendu : '{"x":5,"y":6}'

console.log(
  JSON.stringify([new Number(3), new String("false"), new Boolean(false)]),
);
// Rsultat attendu : '[3,"false",false]'

console.log(JSON.stringify({ x: [10, undefined, function () {}, Symbol("")] }));
// Rsultat attendu : '{"x":[10,null,null,null]}'

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

Syntaxe

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

Paramtres

value

La valeur convertir en chane de caractres JSON.

replacer Facultatif

Une fonction qui modifie le comportement du processus de transformation, ou un tableau de chanes de caractres et de nombres qui dfinit les proprits de value inclure dans le rsultat. Si replacer est un tableau, tous les lments de ce tableau qui ne sont pas des chanes de caractres ou des nombres (qu'ils soient primitifs ou objets enveloppants), y compris les valeurs Symbol, sont compltement ignors. Si replacer n'est ni une fonction ni un tableau (par exemple, null ou non fourni), toutes les proprits de l'objet dont la cl est une chane de caractres sont incluses dans la chane de caractres JSON rsultante.

space Facultatif

Une chane de caractres ou un nombre utilis pour insrer des espaces (y compris l'indentation, les caractres de saut de ligne, etc.) dans la chane de caractres JSON produite afin d'en faciliter la lecture.

Si c'est un nombre, il indique le nombre d'espaces utiliser pour l'indentation, limit 10 (c'est--dire que toute valeur suprieure 10 est traite comme si elle tait 10). Les valeurs infrieures 1 signifient qu'aucun espace ne sera utilis.

Si c'est une chane de caractres, la chane de caractres (ou les 10 premiers caractres de la chane de caractres, si elle est plus longue) est insre avant chaque objet ou tableau imbriqu.

Si space n'est ni une chane de caractres ni un nombre (qu'il s'agisse d'un primitif ou d'un objet enveloppant) par exemple, null ou non fourni aucun espace n'est utilis.

Valeur de retour

Une chane de caractres JSON qui reprsente la valeur indique.

Exceptions

TypeError

Leve dans l'un des cas suivants :

• value contient une rfrence circulaire.
• Une valeur BigInt est rencontre.

Description

JSON.stringify() convertit une valeur en la notation JSON que cette valeur reprsente. Les valeurs sont converties en chane de caractres de la manire suivante :

• Les objets Boolean, Number, String et BigInt (obtenus avec Object()) sont convertis en leur valeur primitive correspondante lors de la conversion, conformment la smantique de conversion traditionnelle. Les objets Symbol (obtenus avec Object()) sont traits comme de simples objets.
• Tenter de srialiser des valeurs BigInt lvera une exception. Cependant, si le BigInt possde une mthode toJSON() (par modification dynamique : BigInt.prototype.toJSON = ...), cette mthode peut fournir le rsultat de la srialisation. Cette contrainte garantit qu'un comportement de srialisation appropri (et, trs probablement, sa dsrialisation associe) est toujours explicitement fourni par l'utilisateurice.
• Les valeurs undefined, Function et Symbol ne sont pas des valeurs JSON valides. Si de telles valeurs sont rencontres lors de la conversion, elles sont soit omises (lorsqu'elles se trouvent dans un objet), soit transformes en null (lorsqu'elles se trouvent dans un tableau). JSON.stringify() peut retourner undefined lorsqu'on lui passe des valeurs  pures  comme JSON.stringify(() => {}) ou JSON.stringify(undefined).
• Les nombres Infinity et NaN, ainsi que la valeur null, sont tous considrs comme null. (Mais contrairement aux valeurs du point prcdent, elles ne seront jamais omises.)
• Les tableaux sont srialiss comme des tableaux (dlimits par des crochets). Seuls les indices de 0 length - 1 (inclus) sont srialiss ; les autres proprits sont ignores.
• L'objet JSON brut spcial cr avec JSON.rawJSON() est srialis comme le texte JSON brut qu'il contient (en accdant sa proprit rawJSON).
• Pour les autres objets :

  • Toutes les proprits dont la cl est un Symbol seront compltement ignores, mme lors de l'utilisation du paramtre replacer.

  • Si la valeur possde une mthode toJSON(), c'est elle de dfinir quelles donnes seront srialises. Au lieu de srialiser l'objet, la valeur retourne par la mthode toJSON() lors de son appel sera srialise. JSON.stringify() appelle toJSON avec un paramtre, key, qui a la mme smantique que le paramtre key de la fonction replacer :

    • si cet objet est une valeur de proprit, le nom de la proprit
    • s'il est dans un tableau, l'indice dans le tableau, sous forme de chane de caractres
    • si JSON.stringify() a t appel directement sur cet objet, une chane vide

    Tous les objets Temporal implmentent la mthode toJSON(), qui retourne une chane de caractres (identique l'appel de toString()). Ainsi, ils seront srialiss comme des chanes de caractres. De mme, les objets Date implmentent toJSON(), qui retourne la mme chose que toISOString().

  • Seules les proprits propres numrables sont parcourues. Cela signifie que Map, Set, etc. deviendront "{}". Vous pouvez utiliser le paramtre replacer pour les srialiser de manire plus utile.

    Les proprits sont parcourues en utilisant le mme algorithme que Object.keys(), qui a un ordre bien dfini et stable entre les implmentations. Par exemple, JSON.stringify sur le mme objet produira toujours la mme chane de caractres, et JSON.parse(JSON.stringify(obj)) produira un objet avec le mme ordre de cls que l'original ( condition que l'objet soit entirement srialisable en JSON).

Le paramtre replacer

Le paramtre replacer peut tre soit une fonction, soit un tableau.

S'il s'agit d'un tableau, ses lments indiquent les noms des proprits de l'objet inclure dans la chane de caractres JSON rsultante. Seules les valeurs de type chanes de caractres et nombres sont prises en compte ; les cls de type symbole sont ignores.

S'il s'agit d'une fonction, elle prend deux paramtres : la cl (key) et la valeur (value) convertir en chane de caractres. L'objet dans lequel la cl a t trouve est fourni comme contexte this de la fonction replacer.

La fonction replacer est galement appele pour l'objet initial convertir, auquel cas la cl (key) est une chane vide (""). Elle est ensuite appele pour chaque proprit de l'objet ou du tableau convertir. Les indices de tableau seront fournis sous forme de chane de caractres comme key. La valeur de la proprit courante sera remplace par la valeur de retour de la fonction replacer pour la conversion en chane de caractres. Cela signifie :

• Si vous retournez un nombre, une chane de caractres, un boolen ou null, cette valeur est directement srialise et utilise comme valeur de la proprit. (Retourner un BigInt lvera galement une exception.)
• Si vous retournez une Function, un Symbol ou undefined, la proprit n'est pas incluse dans le rsultat.
• Si vous retournez un autre objet, l'objet est converti rcursivement en chane de caractres, en appelant la fonction replacer sur chaque proprit.

En gnral, l'indice des lments du tableau ne changera jamais (mme si l'lment est une valeur invalide comme une fonction, il deviendra null au lieu d'tre omis). Utiliser la fonction replacer vous permet de contrler l'ordre des lments du tableau en retournant un tableau diffrent.

Le paramtre space

Le paramtre space peut tre utilis pour contrler les espacements dans la chane de caractres finale.

• S'il s'agit d'un nombre, chaque niveau d'imbrication dans la conversion aura autant d'espaces que ce nombre.
• S'il s'agit d'une chane de caractres, chaque niveau d'imbrication sera indent avec cette chane de caractres.

Chaque niveau d'indentation ne dpassera jamais 10. Les valeurs numriques de space sont limites 10, et les chanes de caractres sont tronques 10 caractres.

Exemples

Utiliser la mthode stringify()

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

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

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

// Les lments de tableau dont la cl est une chane de caractres ne sont pas numrables et n'ont pas de sens en JSON
const a = ["toto", "truc"];
a["tata"] = "quux"; // a: [ 0: 'toto', 1: 'truc', tata: 'quux' ]
JSON.stringify(a);
// '["toto","truc"]'

JSON.stringify({ x: [10, undefined, function () {}, Symbol("")] });
// '{"x":[10,null,null,null]}'

// Structures de donnes classiques
JSON.stringify([
  new Set([1]),
  new Map([[1, 2]]),
  new WeakSet([{ a: 1 }]),
  new WeakMap([[{ a: 1 }, 2]]),
]);
// '[{},{},{},{}]'

// TypedArray
JSON.stringify([new Int8Array([1]), new Int16Array([1]), new Int32Array([1])]);
// '[{"0":1},{"0":1},{"0":1}]'
JSON.stringify([
  new Uint8Array([1]),
  new Uint8ClampedArray([1]),
  new Uint16Array([1]),
  new Uint32Array([1]),
]);
// '[{"0":1},{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Float32Array([1]), new Float64Array([1])]);
// '[{"0":1},{"0":1}]'

// toJSON()
JSON.stringify({
  x: 5,
  y: 6,
  toJSON() {
    return this.x + this.y;
  },
});
// '11'

// Symbols :
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" }, (k, v) => {
  if (typeof k === "symbol") {
    return "a symbol";
  }
});
// undefined

// Proprits non numrables :
JSON.stringify(
  Object.create(null, {
    x: { value: "x", enumerable: false },
    y: { value: "y", enumerable: true },
  }),
);
// '{"y":"y"}'

// Erreur leve pour les valeurs BigInt
JSON.stringify({ x: 2n });
// TypeError: BigInt value can't be serialized in JSON

Utiliser une fonction comme replacer

function replacer(key, value) {
  // Filtrage des proprits
  if (typeof value === "string") {
    return undefined;
  }
  return value;
}

const toto = {
  foundation: "Mozilla",
  model: "box",
  week: 45,
  transport: "car",
  month: 7,
};
JSON.stringify(toto, replacer);
// '{"week":45,"month":7}'

Si vous souhaitez que le replacer distingue l'objet initial d'une proprit dont la cl est une chane de caractres vide (puisque les deux donneraient la chane vide comme cl et potentiellement un objet comme valeur), vous devrez suivre le nombre d'itrations (si celui-ci dpasse la premire itration, il s'agit d'une vritable cl vide).

function makeReplacer() {
  let isInitial = true;

  return (key, value) => {
    if (isInitial) {
      isInitial = false;
      return value;
    }
    if (key === "") {
      // Omet toutes les proprits dont le nom est "" (sauf l'objet initial)
      return undefined;
    }
    return value;
  };
}

const replacer = makeReplacer();
console.log(JSON.stringify({ "": 1, b: 2 }, replacer)); // "{"b":2}"

Utiliser un tableau comme replacer

const toto = {
  foundation: "Mozilla",
  model: "box",
  week: 45,
  transport: "car",
  month: 7,
};

JSON.stringify(toto, ["week", "month"]);
// '{"week":45,"month":7}', ne conserve que les proprits "week" et "month"

Utiliser le paramtre space

Indenter la sortie avec un espace :

console.log(JSON.stringify({ a: 2 }, null, " "));
/*
{
 "a": 2
}
*/

Utiliser un caractre de tabulation imite l'apparence standard de l'impression soigne :

console.log(JSON.stringify({ uno: 1, dos: 2 }, null, "\t"));
/*
{
	"uno": 1,
	"dos": 2
}
*/

Comportement de toJSON()

Dfinir toJSON() pour un objet permet de remplacer son comportement de srialisation.

const obj = {
  data: "data",

  toJSON(key) {
    return key
      ? `Maintenant je suis un objet imbriqu sous la cl '${key}'`
      : this;
  },
};

JSON.stringify(obj);
// '{"data":"data"}'

JSON.stringify({ obj });
// '{"obj":"Maintenant je suis un objet imbriqu sous la cl 'obj'"}'

JSON.stringify([obj]);
// '["Maintenant je suis un objet imbriqu sous la cl '0'"]'

Problme de srialisation des rfrences circulaires

Comme le format JSON (angl.) ne prend pas en charge les rfrences d'objet (bien qu'un brouillon IETF existe), une erreur TypeError sera leve si l'on tente d'encoder un objet contenant des rfrences circulaires.

const referenceCirculaire = {};
referenceCirculaire.moiMeme = referenceCirculaire;

// La srialisation des rfrences circulaires lve "TypeError: cyclic object value"
JSON.stringify(referenceCirculaire);

Pour srialiser des rfrences circulaires, vous pouvez utiliser une bibliothque qui les prend en charge (par exemple, cycle.js(angl.) de Douglas Crockford) ou implmenter vousmme une solution, ce qui ncessitera de trouver et remplacer (ou supprimer) les rfrences cycliques par des valeurs srialisables.

Si vous utilisez JSON.stringify() pour effectuer une copie profonde d'un objet, vous pouvez prfrer utiliser structuredClone(), qui prend en charge les rfrences circulaires. Les API des moteurs JavaScript pour la srialisation binaire, telles que v8.serialize()(angl.), prennent galement en charge les rfrences circulaires.

Utiliser JSON.stringify() avec localStorage

Dans le cas o vous souhaitez stocker un objet cr par votre utilisateur et permettre sa restauration mme aprs la fermeture du navigateur, l'exemple suivant illustre l'utilisation de JSON.stringify() :

// Cration d'un exemple JSON
const session = {
  ecran: [],
  state: true,
};
session.ecran.push({ nom: "cranA", largeur: 450, hauteur: 250 });
session.ecran.push({ nom: "cranB", largeur: 650, hauteur: 350 });
session.ecran.push({ nom: "cranC", largeur: 750, hauteur: 120 });
session.ecran.push({ nom: "cranD", largeur: 250, hauteur: 60 });
session.ecran.push({ nom: "cranE", largeur: 390, hauteur: 120 });
session.ecran.push({ nom: "cranF", largeur: 1240, hauteur: 650 });

// Conversion de l'objet en chane de caractres JSON avec JSON.stringify()
// puis enregistrement dans localStorage sous le nom "session"
localStorage.setItem("session", JSON.stringify(session));

// Exemple montrant comment reconvertir la chane de caractres
// gnre par JSON.stringify() et stocke dans localStorage en objet JSON
const sessionRestauree = JSON.parse(localStorage.getItem("session"));

// La variable sessionRestauree contient maintenant l'objet qui a t sauvegard
// dans localStorage
console.log(sessionRestauree);

JSON.stringify() correctement form

Les moteurs implmentant la spcification JSON.stringify bien forme (angl.) convertiront les substituts isols (tout point de code compris entre U+D800 et U+DFFF) en chanes de caractres l'aide de squences d'chappement Unicode plutt que littralement (en produisant des substituts isols). Avant cette modification, ces chanes de caractres ne pouvaient pas tre encodes en UTF-8 ou UTF-16 valides :

JSON.stringify("\uD800"); // '""'

Mais avec cette modification, JSON.stringify() reprsente des substituts isols l'aide de squences d'chappement JSON qui peuvent tre encodes en UTF-8 ou UTF-16 valides :

JSON.stringify("\uD800"); // '"\\ud800"'

Cette modification devrait tre rtrocompatible tant que vous transmettez le rsultat de JSON.stringify() des API telles que JSON.parse() qui acceptent tout texte JSON valide, car elles traiteront les chappements Unicode des surrogats isols comme identiques aux surrogats isols eux-mmes. Ce n'est que si vous interprtez directement le rsultat de JSON.stringify() que vous devez traiter avec soin les deux encodages possibles de ces points de code par JSON.stringify().

Spcifications

Compatibilit des navigateurs

Voir aussi

• Prothse d'mulation du comportement moderne de JSON.stringify (symbol, unicode bien form, JSON brut) dans core-js
• La mthode JSON.parse()
• La mthode JSON.rawJSON()