JSON.stringify()

El m茅todo JSON.stringify() convierte un objeto o valor de JavaScript en una cadena de texto JSON, opcionalmente reemplaza valores si se indica una funci贸n de reemplazo, o si se especifican las propiedades mediante un array de reemplazo.

Sintaxis

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

Par谩metros

value
El valor que ser谩 convertido a una cadena JSON.
replacerOptional
Una funci贸n que altera el comportamiento del proceso de conversi贸n a cadena de texto, o un array de objetos String o Number que representan una lista de elementos v谩lidos que se incluyen en la cadena JSON. Si este valor es null o no se define, todas las propiedades del objeto son incluidas en la cadena de texto JSON resultante.
spaceOptional
Un objeto de tipo String o Number que se utiliza para insertar un espacio en blanco dentro de la cadena de salida JSON para mejorar su legibilidad.

Si es de tipo Number, indica el n煤mero de espacios a usar como espacios en blanco; este n煤mero est谩 limitado se limita a 10 (si es mayor, el valor es s贸lo 10). Los valores inferiores a 1 indican que no se deben utilizar espacios.

Si es de tipo String, la cadena de texto (o sus 10 primeros caracteres, si es mayor) se utiliza como espacios en blanco. Si este par谩metro no se define o es null, no se utilizar谩 ning煤n espacio en blanco.

Valor devuelto

Una cadena de texto JSON que representa el valor dado.

Excepciones

Lanza una excepci贸n TypeError ("cyclic object value") cuando encuentra una referencia circular.

Descripci贸n

JSON.stringify convierte un valor a notaci贸n JSON represent谩ndolo:

  • Si el valor tiene un m茅todo toJSON(), es responsable de definir qu茅 ser谩 serializado.
  • Los objetos Boolean, Number, and String se convierten a sus valores primitivos, de acuerdo con la conversi贸n sem谩ntica tradicional.
  • Si durante la conversi贸n se encuentra un undefined, una Function, o un Symbol se omite (cuando se encuentra en un objeto) o se censura a null (cuando se encuentra en un array). JSON.stringify() puede devolver undefined cuando se pasan valores "puros" como JSON.stringify(function(){}) o JSON.stringify(undefined).
  • Todas las propiedades que utilicen Symbol en los nombres de la clave se ignoran por completo, incluso si utilizan una funci贸n replacer.
  • Las instancias de Date implementan la funci贸n toJSON() devolviendo una cadena de texto (igual que date.toISOString()). Por lo que son tratadas como strings.
  • Los n煤meros InfinityNaN, as铆 como el valor null, se consideran null.
  • El resto de instancias de Object (incluyendo Map, Set, WeakMap, y WeakSet) s贸lo tendr谩n serializadas sus propiedades enumerables.
JSON.stringify({});                    // '{}'
JSON.stringify(true);                  // 'true'
JSON.stringify('foo');                 // '"foo"'
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(2006, 0, 2, 15, 4, 5))
// '"2006-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]'

// Elementos de array identificados por string no son enumerables y no tienen sentido en JSON
let a = ['foo', 'bar'];
a['baz'] = 'quux';      // a: [ 0: 'foo', 1: 'bar', baz: 'quux' ]
JSON.stringify(a);
// '["foo","bar"]'

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

// Estructuras de datos standard
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'

// S铆mbolos:
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';
  }
});
// undefined

// Propiedades no enumerables:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

El par谩metro replacer

El par谩metro replacer (de reemplazo) puede ser tanto una funci贸n como o un array.

Como una funci贸n toma dos par谩metros: el valor y la clave que van a ser procesados. El objeto al cual pertenece la clave representa el parametro this del reemplazo.

Inicialmente es llamado con una clave vac铆a y representa el objeto que se va a procesar, y solo despu茅s es llamado por cada propiedad en el objeto o array que se va a procesar.

Devuelve el valor que se va a agregar a la cadena JSON, de la siguiente manera:

  • Si se devuelve un n煤mero, la cadena correspondiente es usada como el valor de la propiedad cuando se agrega a la cadena JSON.
  • Si se devuelve una cadena, esta es usuada cono el valor de la propiedad cuando se agrega a la cadena JSON.
  • Si se devuelve un Boolean, true o false son usados como el valor de la propiedad cuando se agrega a la cadena JSON.
  • Si se devuelve alg煤n otro objeto, este es recursivamente procesado en una cadena JSON llamando a la funci贸n de reemplazo para cada propiedad, amenos que el objeto sea una funci贸n, en tal caso nada se agrega a la cadena JSON.
  • Si se devuelve undefined, la propiedad no se incluye en la salida de la cadena JSON.
Nota: No se puede usar la funci贸n de reemplazo para borrar los valores de un array. Si se devuelve undefined o una funci贸n, entonces se usara null en su lugar.

Ejemplo con una funci贸n

function replacer(key, value) {
  // Filtrando propiedades 
  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);
// '{"week":45, "month":7}'

El resultado en una cadena JSON ser铆a:  {"week":45,"month":7}.

Ejemplo con un array

Si el reemplazo es un array, los valores indican los nombres de las propiedades del objeto que se va a incluir en la cadena JSON resultado.

JSON.stringify(foo, ['week', 'month']);  
// '{"week":45,"month":7}', s贸lo mantiene las propiedades de "week" y de "month"

Argumento space

Este argumento puede ser empleado para controlar el espaciado en la cadena final. Si es un n煤mero, los niveles sucesivos del proceso ser谩n identados cada uno por tantos espacios como se indique (hasta 10). Si es una cadena, ser谩n identados con dicha cadena (o los primeros diez caracteres de la misma).

JSON.stringify({ a: 2 }, null, ' ');
// regresa la cadena de texto:
// '{
//  "a": 2
// }'

Usar el car谩cter tabulador simula la apariencia de impresi贸n:

JSON.stringify({ uno: 1, dos : 2 }, null, '\t')
// devuelve el string:
// '{            \
//     "uno": 1, \
//     "dos": 2  \
// }' 

Comportamiento toJSON()

Si un objeto que sera estringificado tiene una propiedad llamada toJSON donde su valor es una funci贸n, entonces el m茅todo toJSON modifica el comportamiento de la estringificaci贸n JSON: en lugar del objeto que esta siendo serializado, el valor retornado por el m茅todo toJSON ser谩 serializado cuando el mismo sea llamado. Por ejemplo:

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

Ejemplo de como usar JSON.stringify() con localStorage

En dado caso en el cual se requiera que un objeto creado por el usuario y al cual se le permita ser restaurado incluso cuando el navegador ha sido cerrado, el siguiente ejemplo es un modelo de la aplicabilidad del metodo JSON. stringify().

Las funciones no son un tipo de dato valido por lo cual estas no funcionaran. Algunos objetos como tipo DATE, se convertiran a cadenas de texto despues de ejecutar JSON.parse().

// Creando un ejemplo de 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 });

// Convirte el JSON string con JSON.stringify()
// entonces guarda con localStorage con el nombre de la sesi贸n
localStorage.setItem('session', JSON.stringify(session));

// Ejemplo de como transformar el String generado usando
// JSON.stringify() y guard谩ndolo en localStorage como objeto JSON otra vez
var restoredSession = JSON.parse(localStorage.getItem('session'));

// Ahora la variable restoredSession contiene el objeto que fue guardado
// en localStorage
console.log(restoredSession);

Especificaciones

Compatibilidad con navegadores

BCD tables only load in the browser

Ver tambi茅n

  • JSON.parse()
  • cycle.js 鈥 Introduces two functions: JSON.decycle and JSON.retrocycle. These allow encoding and decoding of cyclical structures and DAGs into an extended and retrocompatible JSON format.