This page was translated from English by the community.Learn more and join the MDN Web Docs community.
JSON.stringify()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since июль 2015 г..
Сводка
МетодJSON.stringify() возвращает JavaScript-значение, преобразованное в JSON-строку. Возможна замена значений, если какreplacer передана функция, или включение только определённых свойств, если какreplacer указан массив.
Синтаксис
JSON.stringify(value)JSON.stringify(value, replacer)JSON.stringify(value, replacer, space)Параметры
valueЗначение, преобразуемое в строку JSON.
replacerНеобязательныйЕсли является функцией, преобразует значения и свойства по ходу их преобразования в строку; если является массивом, определяет набор свойств, включаемых в объект в окончательной строке.Подробное описание функции
replacerдаётся в статьеИспользование родного объектаJSONруководства по JavaScript.spaceНеобязательныйДелает результат красиво отформатированным (расставляя пробелы).
Описание
МетодJSON.stringify() преобразует значение в представляющую его нотацию JSON со следующими оговорками:
- Порядок преобразования в строку свойств объектов, не являющихся массивами, не гарантируется. Не полагайтесь на порядок свойств во время преобразования.
- Объекты
Boolean,NumberиStringпреобразуются в соответствующие примитивные значения, в соответствии с традиционным соглашением о семантике преобразований. - Значение
undefined, функция или символ, встреченные во время преобразования, будут либо опущены (если они найдены в объекте), либо превращены вnull(если они найдены в массиве). - Все свойства, имеющие ключ в виде символа, будут полностью проигнорированы, даже при использовании функции
replacer.
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]'// Символы: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 "символ"; }});// '{}'Параметрspace
Параметрspace может использоваться для управления форматированием отступов в конечной строке. Если он числовой, каждый последующий уровень вложенности будет дополнен отступом из пробелов, количество которых соответствует уровню (вплоть до десятого уровня). Если он строковый, каждый последующий уровень вложенности будет предваряться этой строкой (или её первыми десятью символами).
JSON.stringify({ a: 2 }, null, " ");// '{// "a": 2// }'Использование символа табуляции имитирует стандартное красивое форматирование:
JSON.stringify({ uno: 1, dos: 2 }, null, "\t");// вернёт строку:// '{// "uno": 1,// "dos": 2// }'Поведение методаtoJSON()
Если преобразуемый в строку объект имеет свойство с именемtoJSON и значением свойства, установленным в функцию, то этот методtoJSON() изменит стандартное поведение преобразования в JSON: вместо преобразования объекта будет использоваться значение, возвращаемое методомtoJSON(). Например:
Предупреждение:Функции не являются допустимыми данными в JSON, так что они не будут работать. Кроме того, некоторые объекты, например, объектDate, станут строками после примененияJSON.parse().
var obj = { foo: "foo", toJSON: function () { return "bar"; },};JSON.stringify(obj); // '"bar"'JSON.stringify({ x: obj }); // '{"x":"bar"}'Пример использования методаJSON.stringify() вместе сlocalStorage
В случае, если вы хотите сохранить объект таким образом, чтобы его можно было восстановить даже после закрытия браузера, имеет смысл воспользоваться следующим примером, демонстрирующим применение методаJSON.stringify():
// Создаём некоторый объектvar session = { screens: [], state: true,};session.screens.push({ name: "экранА", width: 450, height: 250 });session.screens.push({ name: "экранБ", width: 650, height: 350 });session.screens.push({ name: "экранВ", width: 750, height: 120 });session.screens.push({ name: "экранГ", width: 250, height: 60 });session.screens.push({ name: "экранД", width: 390, height: 120 });session.screens.push({ name: "экранЕ", width: 1240, height: 650 });// Преобразуем его в строку JSON с помощью метода JSON.stringify(),// затем сохраняем его в localStorage под именем sessionlocalStorage.setItem("session", JSON.stringify(session));// Пример того, как можно преобразовать строку, полученную с помощью метода// JSON.stringify() и сохранённую в localStorage обратно в объектvar restoredSession = JSON.parse(localStorage.getItem("session"));// Переменная restoredSession содержит объект, который был сохранён// в localStorageconsole.log(restoredSession);Пример использования параметраreplacer
var foo = { foundation: "Mozilla", model: "box", week: 45, transport: "car", month: 7,};JSON.stringify(foo, function (key, value) { if (typeof value === "string") { return undefined; // удаляем все строковые свойства } return value;}); // '{"week":45,"month":7}'JSON.stringify(foo, ["week", "month"]);// '{"week":45,"month":7}', сохранились только свойства week и monthСпецификации
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-json.stringify |