Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

JSON.stringify: de valor JavaScript para texto JSON

JSON.stringify serializa um valor JavaScript como texto JSON; um replacer opcional seleciona ou transforma dados e space controla a indentação.

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

Sintaxe

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

JSON.stringify(value, replacer?, space?) devolve uma string JSON, ou undefined quando o valor de topo é undefined, uma função ou um Symbol. Estes valores são omitidos num objeto, mas tornam-se null num array; NaN e infinitos também se tornam null, enquanto -0 é escrito como 0. Serializa propriedades próprias enumeráveis com chave string na ordem definida de Object.keys; chaves Symbol são ignoradas. A descrição de propriedades próprias enumeráveis aplica-se à lista predefinida; um array replacer lê propriedades nomeadas através de Get e pode incluir uma herdada ou não enumerável.

Um método toJSON, se existir, é executado antes do replacer. Uma função replacer recebe (key, value), com this como contentor, e pode substituir o valor ou omitir uma propriedade devolvendo undefined; a chamada da raiz usa a chave vazia "". Um array replacer forma a lista permitida de nomes de propriedades de objetos. space numérico é limitado a 10 espaços e space string aos primeiros 10 carateres. Para space string, «10 carateres» significa exatamente as primeiras 10 unidades de código UTF-16.

Uma referência cíclica lança TypeError. Um BigInt também lança TypeError, salvo se a procura normal de propriedades encontrar um toJSON invocável; o método pode vir do protótipo. Exceções de getter, toJSON ou replacer propagam-se. A ordem estável das propriedades não torna a saída JSON canónica para assinaturas criptográficas. O método é padrão desde ECMAScript 5; desde ECMAScript 2019, substitutos Unicode isolados são emitidos como sequências \ud800–\udfff, produzindo Unicode bem formado.

Exemplos

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

Resultado

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

Fontes