Questa traduzione è incompleta. Collabora alla traduzione di questo articolo dall’originale in lingua inglese.
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
StringeNumberche 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
StringoNumberusato per inserire spazi nella stringa di output in modo da renderla più leggibile. Se è unNumber, 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 unaString, 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, eStringsono 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 innullse 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.
rimpiazzo per rimuovere valori da un array. Se si restituisce undefined o una funzione, esso verrà rimpiazzato da null.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():
Le funzioni non sono tipi JSON validi, quindi non funzioneranno. Anche gli oggetti come ad esempio Date saranno delle stringhe dopo l'esecuzione di JSON.parse().
// 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
| Specifica | Status | Commento |
|---|---|---|
| ECMAScript 5.1 (ECMA-262) The definition of 'JSON.stringify' in that specification. |
Standard | Definizione iniziale. Implementata in JavaScript 1.7. |
| ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'JSON.stringify' in that specification. |
Standard |
Compatibilità con i Browser
| 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) |