Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

JSON.stringify: da valore JavaScript a testo JSON

JSON.stringify serializza un valore JavaScript in testo JSON; un replacer facoltativo seleziona o trasforma i dati e space controlla l’indentazione.

Versione: ECMAScript 5 onward; well-formed lone-surrogate escaping from ECMAScript 2019; example target: Node.js 24.22.2

Sintassi

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

JSON.stringify(value, replacer?, space?) restituisce una stringa JSON, oppure undefined se il valore principale è undefined, una funzione o un Symbol. Questi valori sono omessi in un oggetto ma diventano null in un array; anche NaN e gli infiniti diventano null, mentre -0 è scritto come 0. Sono serializzate le proprietà proprie enumerabili con chiave stringa nell’ordine definito da Object.keys; le chiavi Symbol sono ignorate. La descrizione delle proprietà proprie enumerabili riguarda l’elenco predefinito; un array replacer legge le proprietà nominate con Get e può includerne una ereditata o non enumerabile.

Un metodo toJSON, se presente, viene eseguito prima del replacer. Una funzione replacer riceve (key, value), con this impostato sul contenitore, e può sostituire il valore oppure omettere una proprietà restituendo undefined; la chiamata radice usa la chiave vuota "". Un array replacer forma l’elenco consentito dei nomi di proprietà degli oggetti. space numerico è limitato a 10 spazi, quello stringa ai primi 10 caratteri. Per space stringa, “10 caratteri” significa esattamente le prime 10 unità di codice UTF-16.

Un riferimento ciclico genera TypeError. Anche un BigInt genera TypeError salvo che la normale ricerca di proprietà trovi un toJSON invocabile; il metodo può provenire dal prototipo. Le eccezioni da getter, toJSON o replacer si propagano. L’ordine stabile delle proprietà non rende l’output JSON canonico per firme crittografiche. Il metodo è standard da ECMAScript 5; da ECMAScript 2019, i surrogati Unicode isolati sono emessi come sequenze \ud800–\udfff, producendo Unicode ben formato.

Esempi

const value = {
  name: "Ada",
  missing: undefined,
  numbers: [1, NaN, Infinity, undefined],
  nested: { keep: true, secret: "hidden" },
};
console.log(JSON.stringify(value, (key, current) =>
  key === "secret" ? undefined : current,
));
console.log(JSON.stringify(undefined) === undefined);

try {
  JSON.stringify(1n);
} catch (error) {
  console.log(error instanceof TypeError);
}

const cycle = {};
cycle.self = cycle;
try {
  JSON.stringify(cycle);
} catch (error) {
  console.log(error instanceof TypeError);
}

Risultato

{"name":"Ada","numbers":[1,null,null,null],"nested":{"keep":true}}
true
true
true

Fonti