los JSON.stringify() El método convierte un objeto o valor de JavaScript en una cadena JSON, reemplazando opcionalmente valores si se especifica una función de reemplazo u opcionalmente incluyendo solo las propiedades especificadas si se especifica una matriz de reemplazo.

Sintaxis

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

Parámetros

value
El valor que se va a convertir en una cadena JSON.
replacerOpcional
Una función que altera el comportamiento del proceso de encadenamiento, o una matriz de String y Number que sirven como una lista de permitidos para seleccionar / filtrar las propiedades del objeto de valor que se incluirá en la cadena JSON. Si este valor es null o no se proporcionan, todas las propiedades del objeto se incluyen en la cadena JSON resultante.
spaceOpcional
A String o Number objeto que se usa para insertar espacios en blanco en la cadena JSON de salida con fines de legibilidad.

Si esto es un Number, indica el número de caracteres de espacio a utilizar como espacio en blanco; este número tiene un límite de 10 (si es mayor, el valor es solo 10). Los valores inferiores a 1 indican que no se debe utilizar ningún espacio.

Si esto es un String, la cadena (o los primeros 10 caracteres de la cadena, si es más larga) se utiliza como espacio en blanco. Si este parámetro no se proporciona (o se null), no se utilizan espacios en blanco.

Valor devuelto

Una cadena JSON que representa el valor dado o indefinido.

Excepciones

  • Lanza un TypeError (“valor de objeto cíclico”) excepción cuando se encuentra una referencia circular.
  • Lanza un TypeError (“El valor de BigInt no se puede serializar en JSON”) al intentar secuenciar un BigInt valor.

Descripción

JSON.stringify() convierte un valor a notación JSON que lo representa:

  • Si el valor tiene un toJSON() método, es responsable de definir qué datos se serializarán.
  • Boolean, Number, y String los objetos se convierten a los valores primitivos correspondientes durante la cadena, de acuerdo con la semántica de conversión tradicional.
  • undefined, Functionarena SymbolLos s no son valores JSON válidos. Si se encuentran tales valores durante la conversión, se omiten (cuando se encuentran en un objeto) o se cambian a null (cuando se encuentra en una matriz). JSON.stringify() puede regresar undefined al pasar valores “puros” como JSON.stringify(function()) o JSON.stringify(undefined).
  • Todos SymbolLas propiedades con clave se ignorarán por completo, incluso cuando se utilice la replacer función.
  • Las instancias de Date implementar el toJSON() función devolviendo una cadena (lo mismo que date.toISOString()). Por lo tanto, se tratan como cadenas.
  • Los números Infinity y NaN, así como el valor null, son todos considerados null.
  • Todo los demás Object instancias (incluyendo Map, Set, WeakMap, y WeakSet) solo tendrán serializadas sus propiedades enumerables.

Ejemplos de

Usando JSON.stringify

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(newDate(2006,0,2,15,4,5))// '"2006-01-02T15:04:05.000Z"'JSON.stringify( x:5, y:6);// '"x":5,"y":6'JSON.stringify([newNumber(3),newString('false'),newBoolean(false)]);// '[3,"false",false]'// String-keyed array elements are not enumerable and make no sense in JSONlet 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]'// Standard data structuresJSON.stringify([newSet([1]),newMap([[1,2]]),newWeakSet([a:1]),newWeakMap([[a:1,2]])]);// '[,,,]'// TypedArrayJSON.stringify([newInt8Array([1]),newInt16Array([1]),newInt32Array([1])]);// '["0":1,"0":1,"0":1]'JSON.stringify([newUint8Array([1]),newUint8ClampedArray([1]),newUint16Array([1]),newUint32Array([1])]);// '["0":1,"0":1,"0":1,"0":1]'JSON.stringify([newFloat32Array([1]),newFloat64Array([1])]);// '["0":1,"0":1]'// toJSON()JSON.stringify( x:5, y:6,toJSON()returnthis.x +this.y;);// '11'// 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';);// undefined// Non-enumerable properties:JSON.stringify( Object.create(null, x: value:'x', enumerable:false, y: value:'y', enumerable:true));// '"y":"y"'// BigInt values throwJSON.stringify(x:2n);// TypeError: BigInt value can't be serialized in JSON

El parámetro de reemplazo

los replacer El parámetro puede ser una función o una matriz.

Como una función, toma dos parámetros: el llave y el valor siendo encordado. El objeto en el que se encontró la clave se proporciona como replacer‘s this parámetro.

Inicialmente, el replacer Se llama a la función con una cadena vacía como clave que representa el objeto que se está secuenciando. Luego se llama para cada propiedad en el objeto o matriz que se está codificando.

Debe devolver el valor que se debe agregar a la cadena JSON, de la siguiente manera:

  • Si devuelve un Number, String, Boolean, o null, la versión en cadena de ese valor se utiliza como valor de la propiedad.
  • Si devuelve un Function, Symbol, o undefined, la propiedad no está incluida en la salida.
  • Si devuelve cualquier otro objeto, el objeto se secuencia recursivamente, llamando al replacer función en cada propiedad.

Nota: No puedes usar el replacer función para eliminar valores de una matriz. Si regresas undefined o una función entonces null se utiliza en su lugar.

Nota: Si desea el replacer para distinguir un objeto inicial de una clave con una propiedad de cadena vacía (ya que ambos darían la cadena vacía como clave y potencialmente un objeto como valor), tendrá que realizar un seguimiento del recuento de iteraciones (si está más allá de la primera iteración, es una clave de cadena vacía genuina).

Reemplazo de ejemplo, en función

functionreplacer(key, value)// Filtering out propertiesif(typeof value ==='string')returnundefined;return value;var foo =foundation:'Mozilla', model:'box', week:45, transport:'car', month:7;JSON.stringify(foo, replacer);// '"week":45,"month":7'

Ejemplo sustituto, como una matriz

Si replacer es una matriz, los valores de la matriz indican los nombres de las propiedades del objeto que deben incluirse en la cadena JSON resultante.

JSON.stringify(foo,['week','month']);// '"week":45,"month":7', only keep "week" and "month" properties

El argumento del espacio

los space El argumento se puede usar para controlar el espaciado en la cadena final.

  • Si es un numero, cada uno de los niveles sucesivos de la cadena tendrá una sangría con este número de caracteres de espacio (hasta 10).
  • Si es una cuerda, los niveles sucesivos serán sangrados por esta cadena (o los primeros diez caracteres).
JSON.stringify( a:2,null,' ');// '//  "a": 2// '

El uso de un carácter de tabulación imita la apariencia estándar de impresión bonita:

JSON.stringify( uno:1, dos:2,null,'t');// returns the string:// '//     "uno": 1,//     "dos": 2// '

comportamiento de toJSON ()

Si un objeto que se va a encadenar tiene una propiedad denominada toJSON cuyo valor es una función, entonces el toJSON() El método personaliza el comportamiento de la cadena JSON: en lugar de serializar el objeto, el valor devuelto por el toJSON() cuando se llame al método, se serializará. JSON.stringify() llamadas toJSON con un parámetro:

  • si este objeto es un valor de propiedad, el nombre de la propiedad
  • si está en una matriz, el índice en la matriz, como una cadena
  • una cadena vacía si JSON.stringify() fue llamado directamente a este objeto

Por ejemplo:

var obj =
    data:'data',toJSON(key)if(key)return`Now I am a nested object under key '$key'`;elsereturnthis;;JSON.stringify(obj);// '"data":"data"'JSON.stringify( obj );// Shorthand property names (ES2015).// '"obj":"Now I am a nested object under key 'obj'"'JSON.stringify([ obj ]);// '["Now I am a nested object under key '0'"]'

Problema con JSON.stringify () al serializar referencias circulares

Tenga en cuenta que desde el Formato JSON no admite referencias a objetos (aunque un El borrador de IETF existe), a TypeError se lanzará si se intenta codificar un objeto con referencias circulares.

const circularReference =;
circularReference.myself = circularReference;// Serializing circular references throws "TypeError: cyclic object value"JSON.stringify(circularReference);

Para serializar referencias circulares, puede usar una biblioteca que las admita (p. Ej. cycle.js por Douglas Crockford) o implementar una solución usted mismo, que requerirá encontrar y reemplazar (o eliminar) las referencias cíclicas por valores serializables.

Problema con JSON.stringify simple para usar como JavaScript

Históricamente, JSON no era un subconjunto completamente estricto de JavaScript. Los puntos de código literal U + 2028 LINE SEPARATOR y U + 2029 PARAGRAPH SEPARATOR podrían aparecer literalmente en cadenas literales y nombres de propiedades en texto JSON. Pero no podían aparecer literalmente en un contexto similar en el texto de JavaScript, solo usando escapes Unicode como u2028 y u2029. Esto cambió recientemente: ahora ambos puntos de código pueden aparecer literalmente en cadenas tanto en JSON como en JavaScript.

Por lo tanto, si se requiere compatibilidad con motores JavaScript más antiguos, es peligroso sustituir directamente la cadena devuelta por JSON.stringify en una cadena de JavaScript para pasar a eval o new Function o como parte de un JSONP URL y se puede utilizar la siguiente utilidad:

functionjsFriendlyJSONStringify(s)returnJSON.stringify(s).replace(/u2028/g,'\u2028').replace(/u2029/g,'\u2029');var s =
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029);tryeval('('+JSON.stringify(s)+')');catch(e)
    console.log(e);// "SyntaxError: unterminated string literal"// No need for a catcheval('('+jsFriendlyJSONStringify(s)+')');// console.log in Firefox unescapes the Unicode if//   logged to console, so we use alertalert(jsFriendlyJSONStringify(s));// "a":"u2028","b":"u2029"

Nota: No se garantiza que las propiedades de los objetos que no son de matriz se encadenen en ningún orden en particular. No confíe en la ordenación de propiedades dentro del mismo objeto dentro de la cadena.

var a =JSON.stringify( foo:"bar", baz:"quux")//'"foo":"bar","baz":"quux"'var b =JSON.stringify( baz:"quux", foo:"bar")//'"baz":"quux","foo":"bar"'
console.log(a !== b)// true// some memoization functions use JSON.stringify to serialize arguments,// which may cause a cache miss when encountering the same object like above

Ejemplo de uso de JSON.stringify () con localStorage

En un caso en el que desee almacenar un objeto creado por su usuario y permitir que se restaure incluso después de que se haya cerrado el navegador, el siguiente ejemplo es un modelo para la aplicabilidad de JSON.stringify():

// Creating an example of JSONvar 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 againvar restoredSession =JSON.parse(localStorage.getItem('session'));// Now restoredSession variable contains the object that was saved// in localStorage
console.log(restoredSession);

JSON.stringify () bien formado

Motores que implementan el especificación JSON.stringify bien formada clasificará los sustitutos solitarios, cualquier punto de código desde U + D800 a U + DFFF, utilizando secuencias de escape Unicode en lugar de literalmente. Antes de este cambio JSON.stringify produciría sustitutos solitarios si la entrada contuviera algún sustituto solitario; dichas cadenas no se pueden codificar en UTF-8 o UTF-16 válidos:

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

Pero con este cambio JSON.stringify representa sustitutos solitarios que utilizan secuencias de escape JSON que pueden estar codificado en UTF-8 o UTF-16 válido:

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

Este cambio debe ser compatible con versiones anteriores siempre que pase el resultado de JSON.stringify a API como JSON.parse que aceptarán cualquier texto JSON válido, porque tratarán los escapes Unicode de los sustitutos solitarios como idénticos a los propios sustitutos solitarios. Solamente si está interpretando directamente el resultado de JSON.stringify ¿Necesitas manejar con cuidado? JSON.stringifydos posibles codificaciones de estos puntos de código.

Especificaciones

Especificación
Especificación del lenguaje ECMAScript (ECMAScript)
# sec-json.stringify

Compatibilidad del navegador

Escritorio Móvil
Cromo Borde Firefox explorador de Internet Ópera Safari WebView Android Chrome Android Firefox para Android Opera Android Safari en IOS Internet de Samsung
stringify 3 12 3,5 8 10,5 4 ≤37 18 4 11 4 1.0
well_formed_stringify 72 79 64 No 60 12,1 72 72 64 50 12,2 No

Ver también

  • JSON.parse()