--- title: JSON.stringify() slug: Web/JavaScript/Reference/Global_Objects/JSON/stringify translation_of: Web/JavaScript/Reference/Global_Objects/JSON/stringify ---
{{JSRef}}
 

Il metodo JSON.stringify() converte un oggetto o un valore JavaScript in una stringa JSON, sostituendo facoltativamente i valori se viene specificata una funzione sostitutiva o facoltativamente includendo solo le proprietà specificate se viene specificato un array replacer.

{{EmbedInteractiveExample("pages/js/json-stringify.html")}}

Sintassi

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

Parametri

value
Il valore da convertire in stringa JSON.
replacer{{optional_inline}}
Una funzione che altera il processo di conversione, o un array di {{jsxref("String")}} e {{jsxref("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.
space{{optional_inline}}
Un oggetto {{jsxref("String")}} o {{jsxref("Number")}} che viene utilizzato per inserire uno spazio bianco nella stringa JSON di output a fini di leggibilità.Se questo è un Number, indica il numero di caratteri dello spazio da usare come spazio bianco; questo numero è limitato a 10 (se è maggiore, il valore è solo 10).Valori inferiori a 1 indicano che non deve essere usato alcuno spazio.

Se si tratta di una  String, la stringa (i primi 10 caratteri della stringa, se è più lunga di quella) viene utilizzata come spazio bianco. Se questo parametro non viene fornito (o è {{JSxRef("null")}}), non viene utilizzato alcuno spazio bianco.

Valore di ritorno

Una stringa JSON che rappresenta il valore dato.

Eccezioni

Genera un'eccezione {{JSxRef("TypeError")}} ("valore dell'oggetto ciclico") quando viene trovato un riferimento circolare.

Descrizione

JSON.stringify() converte un valore in notazione JSON che lo rappresenta:

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

// Simboli:
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';
  }
});
// '{}'

// Proprietà non enumerabili:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

Il parametro replacer

Il parametro replacer può essere una funzione o un array.

Come una funzione, prende due parametri: la chiave e il valore che si sta stringendo. L'oggetto in cui è stata trovata la chiave viene fornito come il parametro this del replacer.

Inizialmente, la funzione replacer viene chiamata con una stringa vuota come chiave che rappresenta l'oggetto da stringificare. Viene quindi chiamato per ogni proprietà sull'oggetto o sull'array da stringificare.

Nota: Non è possibile utilizzare la replacerfunzione per rimuovere i valori da una matrice. Se si restituisce undefinedo una funzione, nullviene invece utilizzata.
Se desideri che il replacer distingua un oggetto iniziale da una chiave con una proprietà stringa vuota (poiché entrambi fornirebbero la stringa vuota come chiave e potenzialmente un oggetto come valore), sarà necessario tenere traccia del conteggio dell'iterazione (se è al di là della prima iterazione, è una vera e propria chiave di stringa vuota).

Esempio di replacer, come funzione

function replacer(key, value) {
  // Filtraggio delle proprietà
  if (typeof value === 'string') {
    return undefined;
  }
  return value;
}

var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
JSON.stringify(foo, replacer);
// Risultato: '{"week":45,"month":7}'

Esempio di replacer, come array

Se replacer è un array, i valori dell'array indicano i nomi delle proprietà nell'oggetto che dovrebbero essere incluse nella stringa JSON risultante.

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

Il parametro space

L'argomento space può essere usato per controllare la spaziatura nella stringa finale.

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

L'utilizzo di un carattere di tabulazione simula l'aspetto standard di tipo "pretty-print":

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

Comportamento di toJSON()

Se un oggetto da stringificare ha una proprietà denominata il toJSON cui valore è una funzione, il metodo toJSON() personalizza il comportamento di stringificazione JSON: invece dell'oggetto serializzato, il valore restituito dal metodo toJSON() quando chiamato verrà serializzato. JSON.stringify() chiama toJSON con un parametro:

Per esempio:

var obj = {
    data: 'data',

    toJSON(key){
        if(key)
            return `Ora sono un oggetto nidificato sotto chiave '${key}'`;

        else
            return this;
    }
};

JSON.stringify(obj);
// '{"data":"data"}'

JSON.stringify({ obj })
// '{"obj":"Ora sono un oggetto nidificato sotto chiave 'obj'"}'

JSON.stringify([ obj ])
// '["Ora sono un oggetto nidificato sotto chiave '0'"]'

Problema con JSON.stringify() durante la serializzazione di riferimenti circolari

Nota che poiché il Formato JSON non supporta i riferimenti agli oggetti (sebbene esista una bozza IETF), {{JSxRef("TypeError")}} verrà generato un se si tenta di codificare un oggetto con riferimenti circolari.

const circularReference = {};
circularReference.myself = circularReference;

// La serializzazione dei riferimenti circolari genera "TypeError: valore dell'oggetto ciclico"
JSON.stringify(circularReference);

Per serializzare i riferimenti circolari è possibile utilizzare una libreria che li supporta (ad es. cycle.js di Douglas Crockford) o implementare una soluzione autonomamente, che richiederà la ricerca e la sostituzione (o la rimozione) dei riferimenti ciclici mediante valori serializzabili.

Problema con plain  JSON.stringify per l'uso come JavaScript

Storicamente, JSON non era un sottoinsieme completamente rigido di JavaScript. I punti del codice letterale U + 2028 LINE SEPARATOR e U + 2029 PARAGRAPH SEPARATOR potrebbero apparire letteralmente in stringhe letterali e nomi di proprietà nel testo JSON. Ma non potevano apparire letteralmente in un contesto simile nel testo JavaScript - solo usando escape Unicode come \u2028 e \u2029.  Questo è cambiato di recente: ora entrambi i punti di codice possono apparire letteralmente nelle stringhe in JSON e JavaScript entrambi.

Pertanto, se è richiesta la compatibilità con i motori JavaScript precedenti, è pericoloso sostituire direttamente la stringa restituita da JSON.stringify una stringa JavaScript da passare a eval o new Function o come parte di un URL JSONP e può essere utilizzata la seguente utility:

function jsFriendlyJSONStringify (s) {
    return JSON.stringify(s).
        replace(/\u2028/g, '\\u2028').
        replace(/\u2029/g, '\\u2029');
}

var s = {
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029)
};
try {
    eval('(' + JSON.stringify(s) + ')');
} catch (e) {
    console.log(e); // "SyntaxError: unterminated string literal"
}

// No need for a catch
eval('(' + jsFriendlyJSONStringify(s) + ')');

// console.log in Firefox scolla l'Unicode se
//   connesso alla console, quindi usiamo alert
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

Note: Non è garantito che le proprietà degli oggetti non array vengano sottoposte a stringa in qualsiasi ordine particolare. Non fare affidamento sull'ordinamento di proprietà all'interno dello stesso oggetto all'interno della stringa.

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

// alcune funzioni di memoizzazione usano JSON.stringify per serializzare gli argomenti,
// mancando la cache quando si incontra lo stesso oggetto come sopra

Esempio di utilizzo JSON.stringify() con localStorage

Nel caso in cui desideri archiviare un oggetto creato dall'utente e consentirne il ripristino anche dopo la chiusura del browser, nell'esempio seguente è disponibile un modello per l'applicabilità di JSON.stringify():

// Creare un 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 });

// Conversione della stringa JSON con JSON.stringify()
// quindi salva con localStorage nel nome della sessione
localStorage.setItem('session', JSON.stringify(session));

// Esempio di come trasformare la stringa generata tramite
// JSON.stringify() e salvare nuovamente in localStorage nell'oggetto JSON
var restoredSession = JSON.parse(localStorage.getItem('session'));

// Ora la variabile restoreSession contiene l'oggetto che è stato salvato
// in localStorage
console.log(restoredSession);

Well-formed JSON.stringify()

Engines implementing the well-formed JSON.stringify specification will stringify lone surrogates -- any code point from U+D800 to U+DFFF -- using Unicode escape sequences rather than literally.  Before this change JSON.stringify would output lone surrogates if the input contained any lone surrogates; such strings could not be encoded in valid UTF-8 or UTF-16:

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

Ma con questo cambiamento JSON.stringify rappresentano surrogati solitari usando sequenze di escape JSON che possono essere codificate in UTF-8 o UTF-16 validi:

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

Questo cambiamento dovrebbe essere retrocompatibile fin tanto che si passa il risultato di JSON.stringify API come JSON.parse quella che accetterà qualsiasi testo JSON valido, in quanto tratterà le escape Unicode dei surrogati soli come identici ai surrogati solitari stessi.  Solo se stai interpretando direttamente il risultato di JSON.stringify hai bisogno di gestire attentamente JSON.stringify le due possibili codifiche di questi punti di codice.

Specifiche

Specifica Stato Commento
{{SpecName('ES5.1', '#sec-15.12.3', 'JSON.stringify')}} {{Spec2('ES5.1')}} Definzione iniziale. Implementato su JavaScript 1.7.
{{SpecName('ES6', '#sec-json.stringify', 'JSON.stringify')}} {{Spec2('ES6')}}  
{{SpecName('ESDraft', '#sec-json.stringify', 'JSON.stringify')}} {{Spec2('ESDraft')}}  

Compatiblità con i browser

{{Compat("javascript.builtins.JSON.stringify")}}

Vedi anche