JSON : mthode statique rawJSON()

Syntaxe

JSON.rawJSON(string)

Paramtres

string

Le texte JSON. Doit tre un JSON valide reprsentant une valeur primitive.

Valeur de retour

Un objet qui peut tre utilis pour crer du texte JSON ayant exactement le mme contenu que la string fournie, sans guillemets autour de la chane ellemme. Cet objet possde un prototype null et est fig (il ne sera donc jamais srialis accidentellement en objet ordinaire par une conversion primitive), et il expose la proprit suivante :

rawJSON

La chane de caractres (string) JSON d'origine fournie.

De plus, il possde un champ priv qui le marque comme un objet JSON brut. Cela permet JSON.stringify() et JSON.isRawJSON() de l'identifier.

Exceptions

SyntaxError

Leve si la chane de caractres (string) n'est pas un JSON valide, ou si elle reprsente un objet ou un tableau.

Description

Un objet JSON brut peut tre vu comme une structure de donnes atomique et immuable, similaire n'importe quel type de primitif. Ce n'est pas un objet ordinaire et il ne contient aucune donne autre que le texte JSON brut. Il sert  prsrialiser  des donnes vers des formats que JSON.stringify ne peut pas produire luimme pour diverses raisons. Le cas d'usage le plus typique est la perte de prcision lie aux nombres virgule flottante. Par exemple :

JSON.stringify({ valeur: 12345678901234567890 });
// {"valeur":12345678901234567000}

La valeur n'est plus exactement quivalente au nombre d'origine ! En JavaScript, les nombres utilisent une reprsentation en virgule flottante et ne peuvent donc pas reprsenter tous les entiers exactement. Le littral numrique 12345678901234567890 est dj arrondi au nombre reprsentable le plus proche lorsqu'il est analys par JavaScript.

Sans JSON.rawJSON, il est impossible d'indiquer JSON.stringify de produire le littral numrique 12345678901234567890, car il n'existe tout simplement aucune valeur numrique JavaScript correspondante. Avec JSON brut, vous pouvez indiquer directement JSON.stringify() comment une valeur particulire doit tre srialise :

const jsonBrut = JSON.rawJSON("12345678901234567890");
JSON.stringify({ valeur: jsonBrut });
// {"valeur":12345678901234567890}

Pour un exemple plus complet, voir Srialisation de nombres sans perte.

Notez que bien que nous ayons pass une chane de caractres JSON.rawJSON(), elle devient tout de mme un nombre dans le JSON final. Cela s'explique parce que la chane de caractres reprsente le texte JSON littral. Si vous souhaitez srialiser une chane de caractres, vous devez utiliser JSON.rawJSON() avec une valeur de chane entoure de guillemets :

const jsonBrut = JSON.rawJSON('"Bonjour le monde"');
JSON.stringify({ valeur: jsonBrut });
// {"valeur":"Bonjour le monde"}

JSON.rawJSON vous permet d'insrer du texte JSON arbitraire, mais ne vous autorise pas crer du JSON invalide. Tout ce qui n'est pas permis par la syntaxe JSON n'est pas non plus permis par JSON.rawJSON() :

const jsonBrut = JSON.rawJSON('"Bonjour\nle monde"'); // Syntax error, because line breaks are not allowed in JSON strings

De plus, vous ne pouvez pas utiliser JSON.rawJSON() pour crer des objets ou des tableaux JSON.

Exemples

Utiliser JSON.rawJSON() pour crer des expressions JSON de diffrents types

const nombreJSON = JSON.rawJSON("123");
const chaineJSON = JSON.rawJSON('"Bonjour le monde"');
const booleenJSON = JSON.rawJSON("true");
const nullJSON = JSON.rawJSON("null");

console.log(
  JSON.stringify({
    age: nombreJSON,
    message: chaineJSON,
    estActif: booleenJSON,
    rien: nullJSON,
  }),
);

// {"age":123,"message":"Bonjour le monde","estActif":true,"rien":null}

Cependant, vous ne pouvez pas utiliser JSON.rawJSON() pour crer des objets ou des tableaux JSON :

const tableauJSON = JSON.rawJSON("[1, 2, 3]");
const objetJSON = JSON.rawJSON('{"a": 1, "b": 2}');
// SyntaxError

Utiliser JSON.rawJSON() pour crer des littraux de chane de caractres chapps

part les nombres, il n'existe qu'un seul autre type qui n'a pas de correspondance un--un entre les valeurs JavaScript et le texte JSON : les chanes de caractres. Lorsque les chanes de caractres sont srialises en JSON, tous les points de code, l'exception de ceux qui ne sont pas lgaux l'intrieur des littraux de chane de caractres JSON (comme les sauts de ligne), sont imprims littralement :

console.log(JSON.stringify({ valeur: "\ud83d\ude04" })); // {"valeur":""}

Cela peut ne pas tre souhaitable, car le rcepteur de cette chane peut grer Unicode diffremment. Pour amliorer l'interoprabilit, vous pouvez dfinir explicitement la chane de caractres srialiser avec des squences d'chappement :

const jsonBrut = JSON.rawJSON('"\\ud83d\\ude04"');
const chaineEnObjet = JSON.stringify({ valeur: jsonBrut });
console.log(chaineEnObjet); // {"valeur":"\ud83d\ude04"}
console.log(JSON.parse(chaineEnObjet).valeur); // 

Notez que les doubles barres obliques dans rawJSON reprsentent en ralit un seul caractre slash.

Spcifications

Compatibilit des navigateurs

Voir aussi

• Prothse d'mulation de JSON.rawJSON dans core-js (angl.)
• L'objet JSON
• La mthode JSON.isRawJSON()
• La mthode JSON.stringify()