JSON.stringify()

Il metodo JSON.stringify() converte un valore JavaScript in una stringa JSON, sostituendo i valori se è specificata una funzione di sostituzione, o includendo le proprietà specificate se un array di valori è specificato.

Sintassi

JSON.stringify(valore[, rimpiazzo[, spazio]])

Parametri

valore

Il valore da convertire in stringa JSON.

rimpiazzoOptional

Una funzione che altera il processo di conversione, o un array di String e Number che contiene le proprietà dell'oggetto che devono essere incluse nella stringa JSON. Se il valore è null o non è specificato, tutte le proprietà dell'oggetto sono incluse nel risultato.

spazio Optional

Un oggetto di tipo String o Number usato per inserire spazi nella stringa di output in modo da renderla più leggibile. Se è un Number, indica il numero di caratteri di spaziatura da usare come spazio; fino ad un massimo di 10 (valori maggiori saranno considerati pari a 10). Valori inferiori a 1 indicano che non vanno usati spazi. Se invece è specificata una String, allora essa (o i suoi primi 10 caratteri, se la lunghezza è maggiore di 10) sarà usata come spazio. Se questo parametro non è specificato o è null, non saranno inseriti spazi.

Descizione

JSON.stringify() converte un valore in notazione JSON:

• Le proprietà degli oggetti che non sono array non sono rappresentate in un particolare ordine, pertanto si consiglia di non fare affidamento sull'ordine di rappresentazione delle proprietà negli oggetti.
• Boolean, Number, e String sono convertiti nel corrispondente valore primitivo, in base alla semantica tradizionale di conversione.
• Se viene incontrato durante la conversione un valore undefined, una funzione, o un simbolo, esso è omesso se compare in un oggetto, o trasformato in null se compare in un array.
• Tutte le proprietà che hanno come chiave un simbolo saranno ignorate, anche se è specificato un rimpiazzo.
• Le proprietà non enumerabili saranno ignorate.

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"}'

Il parametro rimpiazzo

Il parametro rimpiazzo può essere una funzione o un array. Se esso è una funzione, allora riceve due parametri, la chiave e il valore da convertire. Il valore this viene impostato come l'oggetto contenente la proprietà. Inizialmente essa è chiamata con una chiave vuota che rappresenta l'oggetto da convertire, e in seguito essa è chiamata per ogni proprietà dell'oggetto o dell'array da convertire. Il valore di ritorno della funzione dovrebbe essere il valore da aggiungere alla stringa JSON:

• Se si restituisce un Number, esso sarà convertito in stringa e considerato come valore della proprietà da aggiungere nella stringa JSON.
• Se si restituisce una String, la stringa sarà considerata il valore della proprietà da aggiungere nella stringa JSON.
• Se si restituisce un Boolean, "true" o "false" (in base al valore effettivo) sarà considerato il valore della proprietà da aggiungere nella stringa JSON.
• Se si restituisce un altro oggetto, esso sarà ricorsivamente convertito usando la funzione di rimpiazzo su ogni sua proprietà, a meno che l'oggetto non sia una funzione, nel qual caso essa sarà ignorata.
• Se si restituisce undefined, la proprietà sarà ignorata.

Esempio con una funzione

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);

La stringa JSON risultante sarà {"week":45,"month":7}.

Esempio con un array

Se rimpiazzo è un array, i suoi valori indicano i nomi delle proprietà dell'oggetto che saranno inserite nella stringa JSON risultante.

JSON.stringify(foo, ['week', 'month']);  
// '{"week":45,"month":7}', mantiene solo le proprietà "week" e "month"

Il parametro spazio

Il parametro spazio può essere usato per controllare la spaziatura del risultato. Se esso è un numero, i livelli progressivi nella conversione saranno indentati usando come valore il numero specificato (fino a 10). Se esso è una stringa, i livelli saranno indentati usando la stringa (o i suoi primi 10 caratteri).

JSON.stringify({ a: 2 }, null, ' ');
// '{
//  "a": 2
// }'

Usare un carattere di tabulazione simula una pretty-print:

JSON.stringify({ uno: 1, dos: 2 }, null, '\t');
// restituisce la stringa:
// '{
//     "uno": 1,
//     "dos": 2
// }'

Comportamento di toJSON()

Se l'oggetto da convertire possiede una proprietà toJSON il cui valore è una funzione, allora essa permette di personalizzare il comportamento della conversione: invece del processo normale di serializzazione, sarà chiamata la funzione toJSON e usato il suo valore di ritorno. Per esempio:

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

Utilizzo di JSON.stringify() con localStorage

Se si vuole memorizzare un oggetto creato dall'utente per poi caricarlo anche dopo che il browser è stato chiuso, di seguito è riportato un esempio di utilizzo di JSON.stringify():

// Esempio di 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 });

// Converto la stringa JSON con JSON.stringify()
// poi la salvo in localStorage usando session come nome.
localStorage.setItem('session', JSON.stringify(session));

// Esempio di trasformazione della stringa generata da
// JSON.stringify() e salvata in localStorage in un oggetto JSON
var restoredSession = JSON.parse(localStorage.getItem('session'));

// Ora restoredSession contiene l'oggetto che era stato salvato in
// in localStorage
console.log(restoredSession);

Specifiche

Compatibilità con i Browser

Vedi anche

• JSON.parse()