This translation is in progress.
La funció JSON.stringify()
converteix un valor javascript a una cadena de text JSON, opcionalment canviant els valors si hi ha la opció de reempplazador especificada, o optionalment incloient sol les propietats especificades si hi ha declarat un array com especificador.
Syntax
JSON.stringify(value[, replacer[, space]])
Parameters
value
- La variable a convertir a un JSON string.
replacer
Optional- A function that alters the behavior of the stringification process, or an array of
String
andNumber
objects that serve as a whitelist for selecting the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string. space
Optional- A
String
orNumber
object that's used to insert white space into the output JSON string for readability purposes. If this is aNumber
, it indicates the number of space characters to use as white space; this number is capped at 10 if it's larger than that. Values less than 1 indicate that no space should be used. If this is aString
, the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null), no white space is used.
Description
JSON.stringify()
converts a value to JSON notation representing it:
- Properties of non-array objects are not guaranteed to be stringified in any particular order. Do not rely on ordering of properties within the same object within the stringification.
Boolean
,Number
, andString
objects are converted to the corresponding primitive values during stringification, in accord with the traditional conversion semantics.- If
undefined
, a function, or a symbol is encountered during conversion it is either omitted (when it is found in an object) or censored tonull
(when it is found in an array). - All symbol-keyed properties will be completely ignored, even when using the
replacer
function. - Non-enumerable properties will be ignored
JSON.stringify({}); // '{}' JSON.stringify(true); // 'true' JSON.stringify('foo'); // '"foo"' JSON.stringify([1, 'false', false]); // '[1,"false",false]' JSON.stringify({ x: 5 }); // '{"x":5}' 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]' // Symbols: JSON.stringify({ x: undefined, y: Object, z: Symbol('') }); // '{}' JSON.stringify({ [Symbol('foo')]: 'foo' }); // '{}' JSON.stringify({ [Symbol.for('foo')]: 'foo' }, [Symbol.for('foo')]); // '{}' JSON.stringify({ [Symbol.for('foo')]: 'foo' }, function(k, v) { if (typeof k === 'symbol') { return 'a symbol'; } }); // '{}' // Non-enumerable properties: JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) ); // '{"y":"y"}'
The replacer
parameter
The replacer
parameter can be either a function or an array. As a function, it takes two parameters, the key and the value being stringified. The object in which the key was found is provided as the replacer's this
parameter. Initially it gets called with an empty key representing the object being stringified, and it then gets called for each property on the object or array being stringified. It should return the value that should be added to the JSON string, as follows:
- If you return a
Number
, the string corresponding to that number is used as the value for the property when added to the JSON string. - If you return a
String
, that string is used as the property's value when adding it to the JSON string. - If you return a
Boolean
, "true" or "false" is used as the property's value, as appropriate, when adding it to the JSON string. - If you return any other object, the object is recursively stringified into the JSON string, calling the
replacer
function on each property, unless the object is a function, in which case nothing is added to the JSON string. - If you return
undefined
, the property is not included in the output JSON string.
replacer
function to remove values from an array. If you return undefined
or a function then null
is used instead.Example with a function
function replacer(key, value) { if (typeof value === "string") { return undefined; } return value; } var foo = {foundation: "Mozilla", model: "box", week: 45, transport: "car", month: 7}; var jsonString = JSON.stringify(foo, replacer);
The resulting JSON string is {"week":45,"month":7}
.
Example with an array
If replacer
is an array, the array's values indicate the names of the properties in the object that should be included in the resulting JSON string.
JSON.stringify(foo, ['week', 'month']); // '{"week":45,"month":7}', only keep "week" and "month" properties
The space
argument
The space
argument may be used to control spacing in the final string. If it is a number, successive levels in the stringification will each be indented by this many space characters (up to 10). If it is a string, successive levels will indented by this string (or the first ten characters of it).
JSON.stringify({ a: 2 }, null, ' '); // '{ // "a": 2 // }'
Using a tab character mimics standard pretty-print appearance:
JSON.stringify({ uno: 1, dos: 2 }, null, '\t'); // returns the string: // '{ // "uno": 1, // "dos": 2 // }'
toJSON()
behavior
If an object being stringified has a property named toJSON
whose value is a function, then the toJSON()
method customizes JSON stringification behavior: instead of the object being serialized, the value returned by the toJSON()
method when called will be serialized. For example:
var obj = { foo: 'foo', toJSON: function() { return 'bar'; } }; JSON.stringify(obj); // '"bar"' JSON.stringify({ x: obj }); // '{"x":"bar"}'
Example of using JSON.stringify()
with localStorage
In a case where you want to store an object created by your user and allowing it to be restored even after the browser has been closed, the following example is a model for the applicability of JSON.stringify()
:
Functions are not a valid JSON data type so they will not work. Also some objects like Date
will be a string after JSON.parse()
.
// Creating an example of JSON 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 }); // Converting the JSON string with JSON.stringify() // then saving with localStorage in the name of session localStorage.setItem('session', JSON.stringify(session)); // Example of how to transform the String generated through // JSON.stringify() and saved in localStorage in JSON object again var restoredSession = JSON.parse(localStorage.getItem('session')); // Now restoredSession variable contains the object that was saved // in localStorage console.log(restoredSession);
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 5.1 (ECMA-262) The definition of 'JSON.stringify' in that specification. |
Standard | Initial definition. Implemented in JavaScript 1.7. |
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'JSON.stringify' in that specification. |
Standard |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | 3.5 (1.9.1) | 8.0 | 10.5 | 4.0 |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | 1.0 (1.0) | (Yes) | (Yes) | (Yes) |