JSON.stringify()

Sintaxe

JSON.stringify(valor[, replacer[, espao]])

Parmetros

valor

O valor a ser convertido para uma string JSON.

replacer Optional

Uma funo que altera o comportamento do processo de transformao em string, ou um array de objetos String e Number que servem como uma lista branca para selecionar as propriedades do objeto valor a ser includo na string JSON. Se este valor for nulo ou no fornecido, todas as propriedades do objeto so includas na string JSON resultante.

espao Optional

Um objeto String ou Number que usado para inserir espao em branco na sada da string JSON para propsito de legibilidade. Se isto for um Number, indica o nmero de caracteres espao para usar como espao em branco; este nmero limitado em 10 se for maior que isso. Valores menores que 1 indicam que nenhum espao deve ser usado. Se isto for uma String, a string (ou os primeiros 10 caracteres da string, se for maior que isso) usado como espao em branco. Se esse parmetro no for fornecido (ou for null), nenhum espao em branco usado.

Descrio

JSON.stringify() converte um valor para uma notao JSON que o representa:

• Se o valor tiver um mtodo toJSON(), responsvel por definir quais dados sero serializados.
• Boolean, Number, and String os objetos so convertidos para os valores primitivos correspondentes durante a stringificao, de acordo com a semntica de converso.
• Se undefined, uma funo, ou um symbol encontrado durante a converso omitido (quando encontrado em um objeto) ou censurado para null (quando encontrado em um Array). JSON.stringify pode tambm somente retornar undefined ao passar valores puros como JSON.stringify(function(){}) ou JSON.stringify(undefined).
• Todas as propriedades com chave de smbolo sero completamente ignoradas, mesmo quando usar a funo replacer.
• Propriedades no enumerveis sero ignoradas.

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

O parmetro replacer parameter

O parmetro replacer pode ser uma funo ou uma matriz. Como funo, so necessrios dois parmetros, a chave e os valores que esto sendo especificados. O objeto no qual a chave foi encontrada fornecido como substituto desse parmetro. Inicialmente, ele chamado com uma chave vazia que representa o objeto que est sendo codificado e, em seguida, chamado para cada propriedade no objeto ou matriz que est sendo codificada. Ele deve retornar o valor que deve ser adicionado cadeia JSON, da seguinte maneira:

• Se voc retornar um Number, a string correspondente a esse nmero usada como o valor da propriedade quando adicionada sequncia JSON.
• If you return a String, that string is used as the property's value when adding it to the JSON string.
• If you return a Boolean, "true" or "false" is used as the property's value, as appropriate, when adding it to the JSON string.
• If you return any other object, the object is recursively stringified into the JSON string, calling the replacer function on each property, unless the object is a function, in which case nothing is added to the JSON string.
• If you return undefined, the property is not included in the output JSON string.

Exemplo de uma funo

function replacer(key, value) {
  if (typeof value === "string") {
    return undefined;
  }
  return value;
}

var foo = {
  fundao: "Mozilla",
  modelo: "caixa",
  semana: 45,
  transporte: "carro",
  ms: 7,
};
var jsonString = JSON.stringify(foo, replacer);

O resultado do JSON : {"semana":45,"ms":7}.

Exemplo em uma array

Se replacer usado em uma array, os valores da array indicam os nomes das propriedades no objeto, que devem ser includas na sequncia JSON resultante.

JSON.stringify(foo, ["semana", "ms"]);
// '{"semana":45,"ms":7}', apenas mantm as propriedades "semana" e "ms"

O argumento space

O argumento space O argumento pode ser usado para controlar o espaamento na sequncia final. Se for um nmero, os nveis sucessivos na stringficao sero recuados por esse nmero de caracteres de espao (at 10). Se for uma sequncia, os nveis sucessivos sero recuados por essa sequncia (ou pelos dez primeiros caracteres).

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

O uso de um caractere de tabulao imita a aparncia padro de impresso pretty-print.

JSON.stringify({ um: 1, dois: 2 }, null, "\t");
// r:
// '{
//     "um": 1,
//     "dois": 2
// }'

Comportamento de toJSON()

Se um objeto sendo stringificado tiver uma propriedade denominada toJSON() cujo valor uma funo, o mtodo toJSON() personaliza o comportamento da stringificao JSON, em vez de o objeto ser serializado, o valor retornado pelo mtodo toJSON() quando chamado ser serializado. Por exemplo:

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

Exemplo de uso de JSON.stringify() com localStorage

No caso em que voc deseja armazenar um objeto criado por seu usurio e permitir que ele seja restaurado mesmo aps o fechamento do navegador, o exemplo a seguir um modelo para a aplicabilidade de JSON.stringify():

// Criando um exemplo em JSON
var seo = {
  telas: [],
  estado: true,
};
session.screens.push({ nome: "telaA", largura: 450, altura: 250 });
session.screens.push({ nome: "telaB", largura: 650, altura: 350 });
session.screens.push({ nome: "telaC", largura: 750, altura: 120 });
session.screens.push({ nome: "telaD", largura: 250, altura: 60 });
session.screens.push({ nome: "telaE", largura: 390, altura: 120 });
session.screens.push({ nome: "telaF", largura: 1240, altura: 650 });

// Convertendo a string JSON em JSON.stringify()
// Salvando com localStorage no nome da sesso
localStorage.setItem("seo", JSON.stringify(seo));

// Exemplo de como transformar a String gerada por meio de:
// JSON.stringify() e salva em localStorage no objeto JSON novamente
var seoRestaurada = JSON.parse(localStorage.getItem("seo"));

// Agora, a varivel seoRestaurada contm o objeto que foi salvo
// no localStorage
console.log(seoRestaurada);

Especificaes

Compatibilidade em navegadores

Veja tambm

• JSON.parse()