JSON.parse()

Статичний метод JSON.parse() (розібрати) розбирає рядок у форматі JSON, конструюючи значення чи об'єкт JavaScript, описаний рядком. Можна передати функцію як необов'язковий параметр reviver для виконання трансформацій над результівним об'єктом перед його поверненням.

Спробуйте його в дії

Синтаксис

JSON.parse(text)
JSON.parse(text, reviver)

Параметри

text (текст)

Рядок, який буде розібрано як JSON. Опис синтаксису JSON можна знайти в розділі про об'єкт JSON.

reviver (відроджувач) Необов'язкове

Якщо є функцією — цей параметр прописує те, як початкове, сконструйоване під час розбору, значення слід трансформувати перед його поверненням. Невикличні значення ігноруються. Функція викликається з наступними аргументами:

key

Ключ, який відповідає значенню.

value

Значення – результат розбору.

context Необов'язкове

Об'єкт контексту, що зберігає стан, який стосується відродження поточного виразу. Цей об'єкт створюється заново для кожного заклику функції-відроджувача. Він передається лише при відродженні примітивних значень, але не тоді, коли value є об'єктом або масивом. У цього об'єкта є наступна властивість:

source

Вихідний рядок JSON, що представляє це значення.

Повернене значення

Об'єкт, Масив, рядок, число, булеве значення або null, згідно з переданим в text рядком JSON.

Винятки

SyntaxError

Викидається, якщо рядок до розбору не є дійсним JSON.

Опис

JSON.parse() розбирає рядок JSON згідно з граматикою JSON, а потім обчислює рядок так, ніби він був виразом JavaScript. Єдиний випадок, за якого дрібка тексту JSON представляє значення, котре відрізняється від такого самого виразу JavaScript – обробка ключа "__proto__": дивіться Синтаксис літерала об'єкта і JSON.

Параметр reviver

Якщо заданий reviver (відновник), то значення, обчислене при розборі, перетворюється перед поверненням. А саме, обчислене значення і всі його властивості (проходом в глибину), починаючи від властивостей найбільшої вкладеності, й аж до самого кореневого значення – пропускаються крізь reviver.

Параметр reviver при виклику отримує об'єкт, котрий містить властивість, що обробляється, як значення this (якщо не визначити reviver як стрілкову функцію – тоді окремого зв'язування this не буде), а також два аргументи: key та value, котрі представляють ім'я в рядковому вигляді (навіть коли об'єкт є масивом) і значення властивості. У випадку примітивних значень передається додатковий параметр context, який містить вихідний текст значення. Якщо функція reviver повертає undefined (чи не повертає жодного значення – наприклад, коли виконання звалюється з кінця функції), то властивість видаляється з об'єкта. Інакше – властивість перевизначається з поверненим значенням. Якщо reviver перетворює лише частину значень, то слід пересвідчитися, що всі неперетворені значення повертаються як було: інакше вони будуть видалені з результівного об'єкта.

Подібно до параметра JSON.stringify() replacer, щодо масивів і об'єктів, reviver в останню чергу викликається на кореневому об'єкті з порожнім рядком як key й кореневим об'єктом як value. Для решти дійсних значень JSON reviver працює схоже та викликається один раз із порожнім рядком за key та самим значенням за value.

Якщо повернути з reviver інше значення, то це нове значення повністю замінить вихідне значення, що розбиралося. Така логіка застосовується навіть до кореневого значення. Наприклад:

const transformedObj1 = JSON.parse('[1,5,{"s":1}]', (key, value) => {
  return typeof value === "object" ? undefined : value;
});

console.log(transformedObj1); // undefined

Немає узагальненого способу це обійти. Не можна окремо обробляти випадок, коли key є порожнім рядком, тому що об'єкти JSON також можуть містити ключі, що є порожніми рядками. При реалізації відновника потрібно дуже точно знати, яке перетворення потрібно для кожного ключа.

Зверніть увагу, що reviver спрацьовує після розбору значення. Тому, наприклад, числа в тексті JSON вже будуть перетворені на числа JavaScript, в процесі чого можуть втратити частину точності. Одним зі способів передачі великих чисел без втрати точності є серіалізація їх як рядків, а потім відродження до BigInt або іншого відповідного формату довільної точності.

Також можна скористатися властивістю context.source, щоб звернутися до вихідного тексту JSON, який представляє значення, як показано нижче:

const bigJSON = '{"gross_gdp": 12345678901234567890}';
const bigObj = JSON.parse(bigJSON, (key, value, context) => {
  if (key === "gross_gdp") {
    // Ігнорувати значення, оскільки воно вже втратило точність
    return BigInt(context.source);
  }
  return value;
});

Приклади

Застосування JSON.parse()

JSON.parse("{}"); // {}
JSON.parse("true"); // true
JSON.parse('"foo"'); // "foo"
JSON.parse('[1, 5, "false"]'); // [1, 5, "false"]
JSON.parse("null"); // null

Застосування параметра reviver

JSON.parse(
  '{"p": 5}',
  (key, value) =>
    typeof value === "number"
      ? value * 2 // повертає значення * 2 для чисел
      : value, // повертає все інше незмінним
);
// { p: 10 }

JSON.parse('{"1": 1, "2": 2, "3": {"4": 4, "5": {"6": 6}}}', (key, value) => {
  console.log(key);
  return value;
});

// 1
// 2
// 4
// 6
// 5
// 3
// ""

Використання reviver у парі з replacer у JSON.stringify()

Для коректної роботи зі значенням (щоб воно десеріалізувалось до такого самого вихідного об'єкта), процес серіалізації мусить зберігати інформацію про типи. Наприклад, можна застосувати для цього параметр JSON.stringify() replacer:

// Map в загальному випадку серіалізуються як об'єкти без властивостей.
// Можна застосувати замінювач, аби вказати, які записи повинні бути серіалізовані.
const map = new Map([
  [1, "один"],
  [2, "два"],
  [3, "три"],
]);
const jsonText = JSON.stringify(map, (key, value) =>
  value instanceof Map ? Array.from(value.entries()) : value,
);
console.log(jsonText);
// [[1,"один"],[2,"два"],[3,"три"]]
const map2 = JSON.parse(jsonText, (key, value) =>
  Array.isArray(value) ? new Map(value) : value,
);
console.log(map2);
// Map { 1 => "один", 2 => "два", 3 => "три" }

Через те, що JSON не має синтаксичного простору для метаданих з анотаціями типу, для відновлення значень, що не є звичайними об'єктами, слід розглянути наступні варіанти:

• Серіалізувати увесь об'єкт у рядок і додати префікс у вигляді тегу типу.
• "Вгадувати" на основі структури даних (наприклад, масив з масивів двох значень)
• Якщо форма даних – фіксована, то на основі імені властивості (наприклад, всі властивості, що звуться registry, містять об'єкти Map).

JSON.parse() не допускає висячих ком

// обидва викинуть SyntaxError
JSON.parse("[1, 2, 3, 4, ]");
JSON.parse('{"foo" : 1, }');

JSON.parse() не допускає одинарних лапок

// викине SyntaxError
JSON.parse("{'foo': 1}");

Специфікації

Сумісність із браузерами

Дивіться також

• Поліфіл сучасної поведінки JSON.parse (параметр context відроджувача) у складі core-js
• JSON.stringify()