JSON.stringify()

Resumen

El método JSON.stringify() convierte un valor dado en javascript a una cadena  JSON, opcionalmente reemplaza valores si es especificada la función de remplazo, o si se especifican las propiedades mediante un array de reemplazo.

Sintaxis

JSON.stringify(valor[, remplazo [, espacio]])

Parámetros

valor

El valor que será convertido a una cadena JSON.

función de remplazo

Es 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 validos 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.

espacio

Es un objeto de tipo String o Number que es usado para insertar un espacio en blanco dentro de la cadena de salida JSON para su mejor comprensión. Si es un número, se entiende que representa el numero de espacios a agregar; este numero tiene un limite de 10 espacios; numeros menores que 1 inplican que no se utiliza espacio alguno. Si es un cadena (sólo los 10 primeros caracteres son tomados en cuenta), esta  es usada como espacios en blanco. Si este parámetro no se define o este es nulo no se agrega ningun espacio.

Valor devuelto

Un string JSON representando el valor dado.

Descripción

JSON.stringify convierte un valor a notación JSON representándolo:

• Las propiedades de objetos no-array no se garantiza que se realicen en un orden particular. No delegar propiedades de orden en el mismo objeto que se está pasando a JSON.
• Los objetos Boolean, Number, and String se convierten a sus valores primitivos, de acuerdo con la conversión semántica tradicional.
• Si se encuentra undefined, una función, o un valor XML durante la conversión o se omite (cuando se encuentra en un objeto) o se sustituye por null (cuando se encuentra en un array).
• Todas las propiedades symbol-keyed serán completamente ignoradas, aún cuando se utilice la función replacer.
• Propiedades que no se pueden enumerar son ignoradas.

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(new Date(2006, 0, 2, 15, 4, 5))
// '"2006-01-02T15:04:05.000Z"'

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]'

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

// 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';
  }
});
// '{}'
 
// Propiedades no numerables:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

El parámetro de reemplazo

El parámetro de reemplazo pueden ser una función o un array, si es una función requiere de dos parámetros: el valor y su 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 vacia y representa el objeto que se va a procesar, y solo despues 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.

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().

// 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

Basado en Kangax's compat table.

Vea también

• Usando JSON nativo