JSON.stringify() | JavaScript

在此页

句法
描述
范例
规范
浏览器兼容性
另请参阅
相关话题

JSON.stringify() method converts a JavaScript object or value to a JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.

The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

句法

JSON.stringify(value[, replacer[, space]])

参数

value

The value to convert to a JSON string.

replacer 可选

A function that alters the behavior of the stringification process, or an array of


									String

and


									Number

that serve as an allowlist for selecting/filtering the properties of the value object to be included in the JSON string. If this value is


									null

or not provided, all properties of the object are included in the resulting JSON string.

space 可选


									String


									Number

object that's used to insert white space into the output JSON string for readability purposes.

If this is a Number , it indicates the number of space characters to use as white space; this number is capped at 10 (if it is greater, the value is just 10 ). Values less than 1 indicate that no space should be used.

If this is a String , the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null ), no white space is used.

返回值

A JSON string representing the given value.

异常

抛出 TypeError ("cyclic object value") exception when a circular reference is found.
抛出 TypeError ("BigInt value can't be serialized in JSON") when trying to stringify a BigInt 值。

描述

JSON.stringify() converts a value to JSON notation representing it:

If the value has a toJSON() method, it's responsible to define what data will be serialized.
布尔 , Number ，和 String objects are converted to the corresponding primitive values during stringification, in accord with the traditional conversion semantics.
undefined , Function s, and Symbol s are not valid JSON values. If any such values are encountered during conversion they are either omitted (when found in an object) or changed to null (when found in an array). JSON.stringify() can return undefined when passing in "pure" values like JSON.stringify(function(){}) or JSON.stringify(undefined) .
所有 Symbol -keyed properties will be completely ignored, even when using the replacer 函数。
The instances of Date implement the toJSON() function by returning a string (the same as date.toISOString() ). Thus, they are treated as strings.
The numbers Infinity and NaN , as well as the value null , are all considered null .
All the other Object instances (including Map , Set , WeakMap ，和 WeakSet ) will have only their enumerable properties serialized.

范例

Using JSON.stringify

JSON.stringify({});                    // '{}'
JSON.stringify(true);                  // 'true'
JSON.stringify('foo');                 // '"foo"'
JSON.stringify([1, 'false', false]);   // '[1,"false",false]'
JSON.stringify([NaN, null, Infinity]); // '[null,null,null]'
JSON.stringify({ x: 5 });              // '{"x":5}'
JSON.stringify(new Date(2006, 0, 2, 15, 4, 5))
// '"2006-01-02T15:04:05.000Z"'
JSON.stringify({ x: 5, y: 6 });
// '{"x":5,"y":6}'
JSON.stringify([new Number(3), new String('false'), new Boolean(false)]);
// '[3,"false",false]'
// String-keyed array elements are not enumerable and make no sense in JSON
let a = ['foo', 'bar'];
a['baz'] = 'quux';      // a: [ 0: 'foo', 1: 'bar', baz: 'quux' ]
JSON.stringify(a);
// '["foo","bar"]'
JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] });
// '{"x":[10,null,null,null]}'
// Standard data structures
JSON.stringify([new Set([1]), new Map([[1, 2]]), new WeakSet([{a: 1}]), new WeakMap([[{a: 1}, 2]])]);
// '[{},{},{},{}]'
// TypedArray
JSON.stringify([new Int8Array([1]), new Int16Array([1]), new Int32Array([1])]);
// '[{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Uint8Array([1]), new Uint8ClampedArray([1]), new Uint16Array([1]), new Uint32Array([1])]);
// '[{"0":1},{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Float32Array([1]), new Float64Array([1])]);
// '[{"0":1},{"0":1}]'
// toJSON()
JSON.stringify({ x: 5, y: 6, toJSON(){ return this.x + this.y; } });
// '11'
// 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';
  }
});
// undefined
// Non-enumerable properties:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'
// BigInt values throw
JSON.stringify({x: 2n});
// TypeError: BigInt value can't be serialized in JSON

`replacer` parameter

replacer parameter can be either a function or an array.

As a function , it takes two parameters: the key 和 value being stringified. The object in which the key was found is provided as the replacer's this 参数。

Initially, the replacer function is called with an empty string as key representing the object being stringified. It is then called for each property on the object or array being stringified.

It should return the value that should be added to the JSON string, as follows:

If you return a Number , String , 布尔 ，或 null , the stringified version of that value is used as the property's value.
If you return a Function , Symbol , or undefined , the property is not included in the output.
If you return any other object, the object is recursively stringified, calling the replacer function on each property.

注意： You cannot use the replacer function to remove values from an array. If you return undefined or a function then null is used instead.

注意： If you wish the replacer to distinguish an initial object from a key with an empty string property (since both would give the empty string as key and potentially an object as value), you will have to keep track of the iteration count (if it is beyond the first iteration, it is a genuine empty string key).

范例 `replacer` , as a function

function replacer(key, value) {
  // Filtering out properties
  if (typeof value === 'string') {
    return undefined;
  }
  return value;
}
var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
JSON.stringify(foo, replacer);
// '{"week":45,"month":7}'

范例 `replacer` , as an array

若 replacer is an array, the array's values indicate the names of the properties in the object that should be included in the resulting JSON string.

JSON.stringify(foo, ['week', 'month']);
// '{"week":45,"month":7}', only keep "week" and "month" properties

`space` argument

space argument may be used to control spacing in the final string.

If it is a number , successive levels in the stringification will each be indented by this many space characters (up to 10).
If it is a string , successive levels will be indented by this string (or the first ten characters of it).

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

Using a tab character mimics standard pretty-print appearance:

JSON.stringify({ uno: 1, dos: 2 }, null, '\t');
// returns the string:
// '{
//     "uno": 1,
//     "dos": 2
// }'

`toJSON()` behavior

If an object being stringified has a property named toJSON whose value is a function, then the toJSON() method customizes JSON stringification behavior: instead of the object being serialized, the value returned by the toJSON() method when called will be serialized. JSON.stringify() calls toJSON with one parameter:

if this object is a property value, the property name
if it is in an array, the index in the array, as a string
an empty string if JSON.stringify() was directly called on this object

例如：

var obj = {
    data: 'data',
    toJSON (key) {
        if (key)
            return `Now I am a nested object under key '${key}'`;
        else
            return this;
    }
};
JSON.stringify(obj);
// '{"data":"data"}'
JSON.stringify({ obj }); // Shorthand property names (ES2015).
// '{"obj":"Now I am a nested object under key 'obj'"}'
JSON.stringify([ obj ]);
// '["Now I am a nested object under key '0'"]'

Issue with `JSON.stringify()` when serializing circular references

Note that since the JSON format doesn't support object references (although an IETF draft exists ), a TypeError will be thrown if one attempts to encode an object with circular references.

const circularReference = {};
circularReference.myself = circularReference;
// Serializing circular references throws "TypeError: cyclic object value"
JSON.stringify(circularReference);

To serialize circular references you can use a library that supports them (e.g. cycle.js by Douglas Crockford) or implement a solution by yourself, which will require finding and replacing (or removing) the cyclic references by serializable values.

Issue with plain `JSON.stringify` for use as JavaScript

Historically, JSON was not a completely strict subset of JavaScript . The literal code points U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR could appear literally in string literals and property names in JSON text. But they could not appear literally in similar context in JavaScript text, only using Unicode escapes as \u2028 and \u2029 . This recently changed: now both code points may appear literally in strings in JSON and JavaScript both.

Therefore, if compatibility with older JavaScript engines is required, it is perilous to directly substitute the string returned by JSON.stringify into a JavaScript string to be passed to eval or new Function or as part of a JSONP URL, and the following utility can be used:

function jsFriendlyJSONStringify (s) {
    return JSON.stringify(s).
        replace(/\u2028/g, '\\u2028').
        replace(/\u2029/g, '\\u2029');
}
var s = {
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029)
};
try {
    eval('(' + JSON.stringify(s) + ')');
} catch (e) {
    console.log(e); // "SyntaxError: unterminated string literal"
}
// No need for a catch
eval('(' + jsFriendlyJSONStringify(s) + ')');
// console.log in Firefox unescapes the Unicode if
//   logged to console, so we use alert
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

注意 : Properties of non-array objects are not guaranteed to be stringified in any particular order. Do not rely on ordering of properties within the same object within the stringification.

var a = JSON.stringify({ foo: "bar", baz: "quux" })
//'{"foo":"bar","baz":"quux"}'
var b = JSON.stringify({ baz: "quux", foo: "bar" })
//'{"baz":"quux","foo":"bar"}'
console.log(a !== b) // true
// some memoization functions use JSON.stringify to serialize arguments,
// which may cause a cache miss when encountering the same object like above

Example of using `JSON.stringify()` with `localStorage`

In a case where you want to store an object created by your user and allowing it to be restored even after the browser has been closed, the following example is a model for the applicability of JSON.stringify() :

// Creating an example of JSON
var session = {
  'screens': [],
  'state': true
};
session.screens.push({ 'name': 'screenA', 'width': 450, 'height': 250 });
session.screens.push({ 'name': 'screenB', 'width': 650, 'height': 350 });
session.screens.push({ 'name': 'screenC', 'width': 750, 'height': 120 });
session.screens.push({ 'name': 'screenD', 'width': 250, 'height': 60 });
session.screens.push({ 'name': 'screenE', 'width': 390, 'height': 120 });
session.screens.push({ 'name': 'screenF', 'width': 1240, 'height': 650 });
// Converting the JSON string with JSON.stringify()
// then saving with localStorage in the name of session
localStorage.setItem('session', JSON.stringify(session));
// Example of how to transform the String generated through
// JSON.stringify() and saved in localStorage in JSON object again
var restoredSession = JSON.parse(localStorage.getItem('session'));
// Now restoredSession variable contains the object that was saved
// in localStorage
console.log(restoredSession);

Well-formed `JSON.stringify()`

Engines implementing the well-formed JSON.stringify specification will stringify lone surrogates, any code point from U+D800 to U+DFFF, using Unicode escape sequences rather than literally. Before this change JSON.stringify would output lone surrogates if the input contained any lone surrogates; such strings could not be encoded in valid UTF-8 or UTF-16:

JSON.stringify("\uD800"); // '"�"'

But with this change JSON.stringify represents lone surrogates using JSON escape sequences that can be encoded in valid UTF-8 or UTF-16:

JSON.stringify("\uD800"); // '"\\ud800"'

This change should be backwards-compatible as long as you pass the result of JSON.stringify to APIs such as JSON.parse that will accept any valid JSON text, because they will treat Unicode escapes of lone surrogates as identical to the lone surrogates themselves. Only if you are directly interpreting the result of JSON.stringify do you need to carefully handle JSON.stringify 's two possible encodings of these code points.

规范

规范
ECMAScript (ECMA-262) The definition of 'JSON.stringify' in that specification.

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	Desktop						Mobile						Server
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet	Node.js
`stringify`	Chrome 3	Edge 12	Firefox 3.5	IE 8	Opera 10.5	Safari 4	WebView Android ≤37	Chrome Android 18	Firefox Android 4	Opera Android 11	Safari iOS 4	Samsung Internet Android 1.0	nodejs 0.1.100
Well-formed JSON.stringify	Chrome 72	Edge 79	Firefox 64	IE No	Opera 60	Safari 12.1	WebView Android 72	Chrome Android 72	Firefox Android 64	Opera Android 50	Safari iOS 12.2	Samsung Internet Android No	nodejs No

图例

完整支持
不支持

另请参阅

JSON.parse()
cycle.js – Introduces two functions: JSON.decycle and JSON.retrocycle . These allow encoding and decoding of cyclical structures and DAGs into an extended and retrocompatible JSON format.

元数据

最后修改： Jun 16, 2020

标准内置对象
JSON
方法
1. JSON.parse()
2. JSON.stringify()
继承：
Object
特性
1. Object.prototype.__proto__
2. Object.prototype.constructor
方法

在此页

句法

参数

返回值

异常

描述

范例

Using JSON.stringify

replacer parameter

范例 replacer , as a function

范例 replacer , as an array

space argument

toJSON() behavior

Issue with JSON.stringify() when serializing circular references

Issue with plain JSON.stringify for use as JavaScript

Example of using JSON.stringify() with localStorage

Well-formed JSON.stringify()

规范