DieJSON.stringify() statische Methode konvertiert einen JavaScript-Wert in einen JSON-String. Optional können dabei Werte ersetzt werden, wenn einereplacer-Funktion angegeben ist, oder es können nur die spezifizierten Eigenschaften aufgenommen werden, wenn einreplacer-Array angegeben ist.

Probieren Sie es aus

console.log(JSON.stringify({ x: 5, y: 6 }));// Expected output: '{"x":5,"y":6}'console.log(  JSON.stringify([new Number(3), new String("false"), new Boolean(false)]),);// Expected output: '[3,"false",false]'console.log(JSON.stringify({ x: [10, undefined, function () {}, Symbol("")] }));// Expected output: '{"x":[10,null,null,null]}'console.log(JSON.stringify(new Date(2006, 0, 2, 15, 4, 5)));// Expected output: '"2006-01-02T15:04:05.000Z"'

Syntax

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

Parameter

value

Der Wert, der in einen JSON-String umgewandelt werden soll.

replacerOptional

Eine Funktion, die das Verhalten des Stringifizierungsprozesses verändert, oder ein Array von Zeichenketten und Zahlen, die die Eigenschaften vonvalue spezifizieren, die in das Ausgabeergebnis eingefügt werden sollen. Wennreplacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenketten oder Zahlen sind (entweder primitive oder Wrapper-Objekte), einschließlichSymbol-Werten, vollständig ignoriert. Wennreplacer etwas anderes als eine Funktion oder ein Array ist (z.B.null oder nicht angegeben), werden alle mit Zeichenketten gekennzeichneten Eigenschaften des Objekts in den resultierenden JSON-String aufgenommen.

spaceOptional

Eine Zeichenkette oder Zahl, die verwendet wird, um Leerzeichen (einschließlich Einrückungs-, Zeilenumbruchzeichen usw.) in den Ausgabe-JSON-String einzufügen, um die Lesbarkeit zu verbessern.

Wenn dies eine Zahl ist, gibt sie die Anzahl der Leerzeichen an, die als Einrückung verwendet werden sollen, begrenzt auf 10 (das bedeutet, jede Zahl größer als10 wird behandelt, als ob sie10 wäre). Werte kleiner als 1 geben an, dass kein Leerzeichen verwendet werden soll.

Wenn dies eine Zeichenkette ist, wird die Zeichenkette (oder die ersten 10 Zeichen der Zeichenkette, wenn sie länger ist) vor jedem verschachtelten Objekt oder Array eingefügt.

Wennspace etwas anderes als eine Zeichenkette oder Zahl ist (kann entweder ein primitiver oder ein Wrapper-Objekt sein) — zum Beispielnull oder nicht angegeben — werden keine Leerzeichen verwendet.

Rückgabewert

Ein JSON-String, der den angegebenen Wert repräsentiert, oderundefined.

Ausnahmen

TypeError

Wird in einem der folgenden Fälle ausgelöst:

• value enthält eine zirkuläre Referenz.
• EinBigInt-Wert wird angetroffen.

Beschreibung

JSON.stringify() konvertiert einen Wert in die JSON-Notation, die den Wert repräsentiert. Werte werden folgendermaßen stringifiziert:

• Boolean,Number,String, undBigInt (erreichbar überObject()) Objekte werden während der Stringifizierung in die entsprechenden primitiven Werte umgewandelt, gemäß den traditionellen Konvertierungssemantiken.Symbol-Objekte (erreichbar überObject()) werden als einfache Objekte behandelt.
• Der Versuch,BigInt-Werte zu serialisieren, wird einen Fehler werfen. Wenn das BigInt jedoch einetoJSON()-Methode hat (durch Monkey Patching:BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsresultat liefern. Diese Einschränkung stellt sicher, dass vom Benutzer immer explizit ein korrektes Serialisierungs- (und sehr wahrscheinlich das dazugehörige Deserialisierungs-)Verhalten bereitgestellt wird.
• undefined,Function, undSymbol-Werte sind keine gültigen JSON-Werte. Wenn solche Werte während der Konvertierung angetroffen werden, werden sie entweder ausgelassen (wenn sie in einem Objekt gefunden werden) oder innull geändert (wenn sie in einem Array gefunden werden).JSON.stringify() kannundefined zurückgeben, wenn "reine" Werte übergeben werden, wieJSON.stringify(() => {}) oderJSON.stringify(undefined).
• Die ZahlenInfinity undNaN, sowie der Wertnull, werden alle alsnull betrachtet. (Aber im Gegensatz zu den Werten im vorhergehenden Punkt, würden sie niemals ausgelassen.)
• Arrays werden als Arrays (eingeschlossen in eckige Klammern) serialisiert. Nur Array-Indizes zwischen 0 undlength - 1 (einschließlich) werden serialisiert; andere Eigenschaften werden ignoriert.
• Das spezielle rohe JSON-Objekt, das mitJSON.rawJSON() erstellt wird, wird als der rohe JSON-Text serialisiert, den es enthält (durch den Zugriff auf seinerawJSON-Eigenschaft).
• Für andere Objekte:

  • AlleSymbol-gekoppelten Eigenschaften werden vollständig ignoriert, selbst wenn derreplacer Parameter verwendet wird.

  • Wenn der Wert einetoJSON()-Methode hat, ist sie dafür verantwortlich zu definieren, welche Daten serialisiert werden. Anstatt dass das Objekt serialisiert wird, wird der Wert, der von dertoJSON()-Methode zurückgegeben wird, wenn sie aufgerufen wird, serialisiert.JSON.stringify() rufttoJSON mit einem Parameter auf, demkey, der die gleiche Semantik wie derkey-Parameter derreplacer Funktion hat:

    • wenn dieses Objekt ein Eigenschaftswert ist, der Eigenschaftenname
    • wenn es sich in einem Array befindet, der Index im Array, als String
    • wennJSON.stringify() direkt auf dieses Objekt aufgerufen wurde, ein leerer String

    AlleTemporal-Objekte implementieren dietoJSON()-Methode, die eine Zeichenkette zurückgibt (dieselbe wie bei Aufruf vontoString()). Daher werden sie als Zeichenketten serialisiert. Ähnlich implementierenDate-ObjektetoJSON(), was dasselbe zurückgibt wietoISOString().

  • Nurenumerable eigene Eigenschaften werden besucht. Dies bedeutet, dassMap,Set, usw. zu"{}" werden. Sie können denreplacer-Parameter verwenden, um sie in etwas nützlicheres zu serialisieren.

    Eigenschaften werden mit demselben Algorithmus besucht wieObject.keys(), der eine wohl definierte Ordnung hat und konsistent über Implementierungen hinweg ist. Zum Beispiel wirdJSON.stringify für dasselbe Objekt immer denselben String erzeugen, undJSON.parse(JSON.stringify(obj)) würde ein Objekt mit derselben Schlüsselreihenfolge wie das Original erzeugen (vorausgesetzt, das Objekt ist vollständig JSON-serialisierbar).

Derreplacer-Parameter

Derreplacer-Parameter kann entweder eine Funktion oder ein Array sein.

Als Array geben seine Elemente die Namen der Eigenschaften im Objekt an, die im resultierenden JSON-String enthalten sein sollten. Es werden nur Zeichenketten- und Zahlenwerte berücksichtigt; Symbol-Schlüssel werden ignoriert.

Als Funktion nimmt er zwei Parameter an: denkey und denvalue, die stringifiziert werden. Das Objekt, in dem der Schlüssel gefunden wurde, wird alsthis-Kontext desreplacer bereitgestellt.

Diereplacer-Funktion wird auch für das ursprünglich stringifizierte Objekt aufgerufen, in welchem Fall derkey ein leerer String ("") ist. Anschließend wird sie für jede Eigenschaft des Objekts oder Arrays, das stringifiziert wird, aufgerufen. Array-Indizes werden alskey in ihrer String-Form bereitgestellt. Der aktuelle Eigenschaftswert wird mit dem Rückgabewert desreplacer für die Stringifizierung ersetzt. Das bedeutet:

• Wenn Sie eine Zahl, eine Zeichenkette, einen booleschen Wert odernull zurückgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Das Zurückgeben eines BigInt wird ebenfalls einen Fehler werfen.)
• Wenn Sie eineFunction, einSymbol oderundefined zurückgeben, wird die Eigenschaft nicht in der Ausgabe enthalten.
• Wenn Sie ein anderes Objekt zurückgeben, wird das Objekt rekursiv stringifiziert, wobei diereplacer-Funktion für jede Eigenschaft aufgerufen wird.

Typischerweise verschieben sich Array-Elemente nie (selbst wenn das Element ein ungültiger Wert wie eine Funktion ist, wird es zunull statt ausgelassen). Mit derreplacer-Funktion können Sie die Reihenfolge der Array-Elemente steuern, indem Sie ein anderes Array zurückgeben.

Derspace-Parameter

Derspace-Parameter kann verwendet werden, um Abstände im finalen String zu steuern.

• Wenn er eine Zahl ist, werden nachfolgende Ebenen in der Stringification jeweils um diese Anzahl an Leerzeichen eingerückt.
• Wenn er eine Zeichenkette ist, werden nachfolgende Ebenen mit dieser Zeichenkette eingerückt.

Jede Einrückungsebene wird nie länger als 10 sein. Zahlenwerte vonspace werden auf 10 begrenzt, und Zeichenkettenwerte werden auf 10 Zeichen abgeschnitten.

Beispiele

Verwendung von 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(1906, 0, 2, 15, 4, 5));// '"1906-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 JSONconst 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 structuresJSON.stringify([  new Set([1]),  new Map([[1, 2]]),  new WeakSet([{ a: 1 }]),  new WeakMap([[{ a: 1 }, 2]]),]);// '[{},{},{},{}]'// TypedArrayJSON.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" }, (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 throwJSON.stringify({ x: 2n });// TypeError: BigInt value can't be serialized in JSON

Verwendung einer Funktion alsreplacer

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

Wenn Sie möchten, dass derreplacer ein initiales Objekt von einem Schlüssel mit einer leeren Zeichenketten-Eigenschaft unterscheidet (da beide den leeren String als Schlüssel und möglicherweise ein Objekt als Wert geben würden), müssen Sie die Iterationsanzahl verfolgen (wenn es über die erste Iteration hinaus ist, ist es ein echter leerer String-Schlüssel).

function makeReplacer() {  let isInitial = true;  return (key, value) => {    if (isInitial) {      isInitial = false;      return value;    }    if (key === "") {      // Omit all properties with name "" (except the initial object)      return undefined;    }    return value;  };}const replacer = makeReplacer();console.log(JSON.stringify({ "": 1, b: 2 }, replacer)); // "{"b":2}"

Verwendung eines Arrays alsreplacer

const foo = {  foundation: "Mozilla",  model: "box",  week: 45,  transport: "car",  month: 7,};JSON.stringify(foo, ["week", "month"]);// '{"week":45,"month":7}', only keep "week" and "month" properties

Verwendung desspace-Parameters

Den Ausgabe-String mit einem Leerzeichen einrücken:

console.log(JSON.stringify({ a: 2 }, null, " "));/*{ "a": 2}*/

Verwendung eines Tabulatorzeichens imitiert das standardmäßige Formatieren von Text:

console.log(JSON.stringify({ uno: 1, dos: 2 }, null, "\t"));/*{"uno": 1,"dos": 2}*/

toJSON()-Verhalten

Die Definition vontoJSON() für ein Objekt ermöglicht es, sein Serialisierungsverhalten zu überschreiben.

const obj = {  data: "data",  toJSON(key) {    return key ? `Now I am a nested object under key '${key}'` : this;  },};JSON.stringify(obj);// '{"data":"data"}'JSON.stringify({ obj });// '{"obj":"Now I am a nested object under key 'obj'"}'JSON.stringify([obj]);// '["Now I am a nested object under key '0'"]'

Problem beim Serialisieren von zirkulären Referenzen

Da dasJSON-Format keine Objekt-Referenzen unterstützt (obwohl einIETF-Entwurf existiert), wird einTypeError geworfen, wenn versucht wird, ein Objekt mit zirkulären Referenzen zu kodieren.

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

Um zirkuläre Referenzen zu serialisieren, können Sie eine Bibliothek verwenden, die sie unterstützt (z.B.cycle.js von Douglas Crockford) oder eine Lösung selbst implementieren, die das Finden und Ersetzen (oder Entfernen) der zyklischen Referenzen durch serialisierbare Werte erfordert.

Wenn SieJSON.stringify() verwenden, um ein Objekt tief zu kopieren, möchten Sie stattdessen möglicherweisestructuredClone() verwenden, das zirkuläre Referenzen unterstützt. JavaScript-Engine-APIs für die binäre Serialisierung, wiev8.serialize(), unterstützen ebenfalls zirkuläre Referenzen.

Verwendung von JSON.stringify() mit localStorage

In einem Fall, in dem Sie ein vom Benutzer erstelltes Objekt speichern und es wiederherstellen möchten, auch nachdem der Browser geschlossen wurde, ist das folgende Beispiel ein Modell für die Anwendbarkeit vonJSON.stringify():

// Creating an example of JSONconst 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 sessionlocalStorage.setItem("session", JSON.stringify(session));// Example of how to transform the String generated through// JSON.stringify() and saved in localStorage in JSON object againconst restoredSession = JSON.parse(localStorage.getItem("session"));// Now restoredSession variable contains the object that was saved// in localStorageconsole.log(restoredSession);

Well-formed JSON.stringify()

Engines, die diewell-formed JSON.stringify spec implementieren, werden Lone-Surrogates (beliebiger Codepunkt von U+D800 bis U+DFFF) unter Verwendung von Unicode-Escape-Sequenzen anstelle von wörtlicher Darstellung (Ausgabe von Lone-Surrogates) stringifizieren. Vor dieser Änderung konnten solche Zeichenketten nicht in gültigem UTF-8 oder UTF-16 kodiert werden:

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

Aber mit dieser Änderung stelltJSON.stringify() Lone-Surrogates unter Verwendung von JSON-Escape-Sequenzen dar, diekönnen in gültigem UTF-8 oder UTF-16 kodiert werden:

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

Diese Änderung sollte rückwärtskompatibel sein, solange Sie das Ergebnis vonJSON.stringify() an APIs wieJSON.parse() übergeben, die jeden gültigen JSON-Text akzeptieren, da sie Unicode-Escapes von Lone-Surrogates als identisch mit den Lone-Surrogates selbst behandeln.Nur wenn Sie das Ergebnis vonJSON.stringify() direkt interpretieren, müssen SieJSON.stringify()'s zwei mögliche Kodierungen dieser Codepunkte sorgfältig handhaben.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill of modernJSON.stringify behavior (symbol, well-formed unicode, raw JSON) incore-js
• JSON.parse()
• JSON.rawJSON()