HOWTO · JavaScript

Converter JSON em objeto em JavaScript

Este tutorial demonstra como transformar com segurança a string JSON em um objeto.

Nesta página

Use JSON.parse() para converter uma string formatada como JSON em um valor JavaScript. Quando o documento JSON representa um objeto, o resultado é um objeto JavaScript cujas propriedades podem ser lidas e usadas. A análise não valida as regras da sua aplicação, não transforma strings de data em objetos Date nem torna seguros para uso em HTML valores não confiáveis. Os exemplos a seguir mostram a conversão básica, o tratamento de entradas malformadas, o acesso a propriedades aninhadas e a conversão de datas.

O que a análise de JSON retorna

JSON é um formato de texto que representa valores como objetos, arrays, strings, números, valores booleanos e null. Uma string JSON é texto; após a análise, o JavaScript fornece o valor correspondente. Um documento que representa um objeto resulta em um objeto, enquanto um array JSON resulta em um array. O resultado da análise não é necessariamente um objeto, portanto o código deve levar em conta a estrutura esperada para a entrada.

A sintaxe JSON é mais restrita que a sintaxe de literais de objeto do JavaScript. As chaves dos objetos e os valores de string precisam usar aspas duplas, e JSON não permite comentários, funções nem vírgulas finais. Por exemplo, {"name":"Ari","active":true} é texto JSON, mas {name: 'Ari', active: true} não é. Essas regras explicam por que nem sempre é possível passar diretamente ao analisador um literal de objeto JavaScript.

Converter uma string JSON com JSON.parse()

Passe a string para JSON.parse() e use o valor retornado como qualquer outro dado JavaScript. Este exemplo analisa o registro de uma pessoa e lê duas de suas propriedades:

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

const jsonText = '{"name":"Ari","age":30}';
const person = JSON.parse(jsonText);

console.log(person.name);
console.log(person.age);

O primeiro registro no console mostra o nome, e o segundo mostra a idade numérica. O acesso às propriedades funciona porque o documento JSON representa um objeto. Se a entrada já for um objeto JavaScript, não o transforme em string só para analisá-lo novamente; JSON.parse() espera texto JSON.

Tratar JSON inválido

Se a string estiver malformada ou não tiver uma sintaxe JSON válida, JSON.parse() lança um SyntaxError. Capture esse erro quando a entrada puder vir de um arquivo, de uma solicitação ou de outra fonte cujo formato talvez não seja o esperado. Mantenha o tratamento de erros próximo da operação de análise para que o código chamador possa decidir o que fazer em seguida:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

const jsonText = '{"name":"Ari",}';
let person;

try {
  person = JSON.parse(jsonText);
  console.log(person.name);
} catch (error) {
  console.log("Could not parse JSON");
}

Este exemplo exibe uma mensagem curta da aplicação quando encontra a vírgula final inválida. A mensagem mostrada no código, Could not parse JSON, permanece em inglês. Em código de produção, você pode registrar o erro nos logs da aplicação ou mostrar uma mensagem de validação útil. Evite registrar dados confidenciais ou expor detalhes internos do erro aos usuários. Uma análise bem-sucedida confirma apenas que o texto segue a sintaxe JSON; verifique separadamente as propriedades obrigatórias e os tipos dos valores antes de depender deles.

Ler valores aninhados

Objetos e arrays aninhados são analisados como valores JavaScript aninhados; por isso, acesse-os com a notação habitual de propriedades e índices. O próximo exemplo lê uma cidade de um objeto de endereço e o primeiro item de um array:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

const jsonText = '{"person":{"name":"Ari","address":{"city":"Oslo"}},"scores":[8,9]}';
const data = JSON.parse(jsonText);

console.log(data.person.address.city);
console.log(data.scores[0]);

A estrutura esperada é importante: se person, address ou scores não existir ou tiver um tipo diferente, o acesso direto à propriedade talvez não forneça o valor esperado pela aplicação. Se os dados tiverem um esquema, valide o valor analisado antes de acessar propriedades profundas. A análise também não mescla objetos nem converte nomes de propriedades; ela recria os valores representados no texto JSON.

Converter strings de data após a análise

JSON não tem um tipo de data, então as datas são representadas como strings. A análise mantém essas strings inalteradas. Depois de analisar o texto, converta explicitamente uma propriedade de data conhecida com new Date() e use um valor no formato ISO padrão com indicação de fuso horário quando a origem representar um instante específico:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

const jsonText = '{"createdAt":"2024-01-15T12:30:00Z"}';
const data = JSON.parse(jsonText);
const createdAt = new Date(data.createdAt);

console.log(createdAt instanceof Date);

new Date() cria um objeto JavaScript Date a partir da string; Date() sem new retorna uma string. A análise de datas pode depender do formato de entrada, portanto normalize as datas na origem dos dados e verifique se o resultado é uma data válida quando a fonte não for confiável. Converta apenas os campos que a aplicação trata como datas; o analisador JSON não os identifica automaticamente.