JSON.rawJSON()

Статический метод JSON.rawJSON() создает объект "сырого JSON", содержащий фрагмент текста JSON. При сериализации в JSON объект сырого JSON обрабатывается так, как будто он уже является фрагментом JSON. Этот текст должен быть действительным JSON.

Синтаксис

JSON.rawJSON(string)

Параметры

string

Текст JSON. Должен быть действительным JSON, представляющим примитивное значение.

Возвращаемое значение

Объект, который можно использовать для создания текста JSON с тем же содержимым, что и предоставленный string, без кавычек вокруг самой строки. Этот объект имеет null прототип и заморожен (поэтому он никогда случайно не сериализуется как обычный объект каким-либо видом примитивного преобразования) и имеет следующее свойство:

rawJSON

Исходный текст JSON string.

Кроме того, он имеет приватное поле, которое помечает его как объект сырого JSON. Это позволяет идентифицировать его с помощью JSON.stringify() и JSON.isRawJSON().

Исключения

SyntaxError

Выбрасывается, если string не является действительным JSON, или если он представляет объект или массив.

Описание

Объект сырого JSON можно рассматривать как неизменяемую, атомарную структуру данных, подобную любому примитиву. Это не обычный объект, и он не содержит никаких данных, кроме самого текста JSON. Он используется для "предварительной сериализации" данных в форматы, которые JSON.stringify сам не может создавать по различным причинам. Наиболее распространенным случаем использования является проблема потери точности при числах с плавающей запятой. Например:

JSON.stringify({ value: 12345678901234567890 });
// {"value":12345678901234567000}

Значение больше не точно эквивалентно исходному числу! Это связано с тем, что JavaScript использует представление с плавающей запятой для всех чисел, поэтому оно не может точно представить все целые числа. Сам числовой литерал 12345678901234567890 уже округляется до ближайшего представимого числа при его разборе JavaScript.

Без JSON.rawJSON нет способа указать JSON.stringify создать числовой литерал 12345678901234567890, поскольку соответствующего значения числа JavaScript просто нет. С помощью сырого JSON вы можете напрямую указать JSON.stringify(), как должно быть сериализовано определенное значение:

const rawJSON = JSON.rawJSON("12345678901234567890");
JSON.stringify({ value: rawJSON });
// {"value":12345678901234567890}

Более полный пример этого см. в разделе Lossless number serialization.

Обратите внимание, что, хотя мы передали строку в JSON.rawJSON(), в конечном JSON она все равно становится числом. Это связано с тем, что строка представляет собой точный текст JSON. Если вы хотите сериализовать строку, вам следует использовать JSON.rawJSON() со строковым значением в кавычках:

const rawJSON = JSON.rawJSON('"Hello world"');
JSON.stringify({ value: rawJSON });
// {"value":"Hello world"}

JSON.rawJSON позволяет вставлять произвольный текст JSON, но не позволяет создавать недопустимый JSON. Все, что не допускалось синтаксисом JSON, не допускается и JSON.rawJSON():

const rawJSON = JSON.rawJSON('"Hello\nworld"'); // Syntax error, because line breaks are not allowed in JSON strings

Кроме того, вы не можете использовать JSON.rawJSON() для создания объектов или массивов JSON.

Примеры

Использование JSON.rawJSON() для создания JSON-выражений различных типов

const numJSON = JSON.rawJSON("123");
const strJSON = JSON.rawJSON('"Hello world"');
const boolJSON = JSON.rawJSON("true");
const nullJSON = JSON.rawJSON("null");

console.log(
  JSON.stringify({
    age: numJSON,
    message: strJSON,
    isActive: boolJSON,
    nothing: nullJSON,
  }),
);

// {"age":123,"message":"Hello world","isActive":true,"nothing":null}

Однако вы не можете использовать JSON.rawJSON() для создания объектов или массивов JSON:

const arrJSON = JSON.rawJSON("[1, 2, 3]");
const objJSON = JSON.rawJSON('{"a": 1, "b": 2}');
// SyntaxError

Использование JSON.rawJSON() для создания экранированных строковых литералов

Помимо чисел, существует только один другой тип, который не имеет однозначного соответствия между значениями JavaScript и текстом JSON: строки. При сериализации строк в JSON все кодовые точки, кроме тех, которые недопустимы внутри строковых литералов JSON (например, разрывы строк), выводятся буквально:

console.log(JSON.stringify({ value: "\ud83d\ude04" })); // {"value":"😄"}

Это может быть нежелательно, поскольку получатель этой строки может обрабатывать Unicode по-разному. Для улучшения совместимости вы можете явно указать, что строка должна быть сериализована с использованием escape-последовательностей:

const rawJSON = JSON.rawJSON('"\\ud83d\\ude04"');
const objStr = JSON.stringify({ value: rawJSON });
console.log(objStr); // {"value":"\ud83d\ude04"}
console.log(JSON.parse(objStr).value); // 😄

Обратите внимание, что двойные обратные косые черты в rawJSON на самом деле представляют собой один символ косой черты.

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

Совместимость с браузерами

См. также

• Polyfill JSON.rawJSON в core-js
• JSON
• JSON.isRawJSON()
• JSON.stringify()