JSON.stringify()

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.

replacer Optional

Eine Funktion, die das Verhalten des Stringifizierungsprozesses verndert, oder ein Array von Zeichenketten und Zahlen, die die Eigenschaften von value spezifizieren, die in das Ausgabeergebnis eingefgt werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenketten oder Zahlen sind (entweder primitive oder Wrapper-Objekte), einschlielich Symbol-Werten, vollstndig ignoriert. Wenn replacer 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.

space Optional

Eine Zeichenkette oder Zahl, die verwendet wird, um Leerzeichen (einschlielich Einrckungs-, Zeilenumbruchzeichen usw.) in den Ausgabe-JSON-String einzufgen, um die Lesbarkeit zu verbessern.

Wenn dies eine Zahl ist, gibt sie die Anzahl der Leerzeichen an, die als Einrckung verwendet werden sollen, begrenzt auf 10 (das bedeutet, jede Zahl grer als 10 wird behandelt, als ob sie 10 wre). 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 lnger ist) vor jedem verschachtelten Objekt oder Array eingefgt.

Wenn space etwas anderes als eine Zeichenkette oder Zahl ist (kann entweder ein primitiver oder ein Wrapper-Objekt sein) zum Beispiel null oder nicht angegeben werden keine Leerzeichen verwendet.

Rckgabewert

Ein JSON-String, der den angegebenen Wert reprsentiert, oder undefined.

Ausnahmen

TypeError

Wird in einem der folgenden Flle ausgelst:

• value enthlt eine zirkulre Referenz.
• Ein BigInt-Wert wird angetroffen.

Beschreibung

JSON.stringify() konvertiert einen Wert in die JSON-Notation, die den Wert reprsentiert. Werte werden folgendermaen stringifiziert:

• Boolean, Number, String, und BigInt (erreichbar ber Object()) Objekte werden whrend der Stringifizierung in die entsprechenden primitiven Werte umgewandelt, gem den traditionellen Konvertierungssemantiken. Symbol-Objekte (erreichbar ber Object()) werden als einfache Objekte behandelt.
• Der Versuch, BigInt-Werte zu serialisieren, wird einen Fehler werfen. Wenn das BigInt jedoch eine toJSON()-Methode hat (durch Monkey Patching: BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsresultat liefern. Diese Einschrnkung stellt sicher, dass vom Benutzer immer explizit ein korrektes Serialisierungs- (und sehr wahrscheinlich das dazugehrige Deserialisierungs-)Verhalten bereitgestellt wird.
• undefined, Function, und Symbol-Werte sind keine gltigen JSON-Werte. Wenn solche Werte whrend der Konvertierung angetroffen werden, werden sie entweder ausgelassen (wenn sie in einem Objekt gefunden werden) oder in null gendert (wenn sie in einem Array gefunden werden). JSON.stringify() kann undefined zurckgeben, wenn "reine" Werte bergeben werden, wie JSON.stringify(() => {}) oder JSON.stringify(undefined).
• Die Zahlen Infinity und NaN, sowie der Wert null, werden alle als null betrachtet. (Aber im Gegensatz zu den Werten im vorhergehenden Punkt, wrden sie niemals ausgelassen.)
• Arrays werden als Arrays (eingeschlossen in eckige Klammern) serialisiert. Nur Array-Indizes zwischen 0 und length - 1 (einschlielich) werden serialisiert; andere Eigenschaften werden ignoriert.
• Das spezielle rohe JSON-Objekt, das mit JSON.rawJSON() erstellt wird, wird als der rohe JSON-Text serialisiert, den es enthlt (durch den Zugriff auf seine rawJSON-Eigenschaft).
• Fr andere Objekte:

  • Alle Symbol-gekoppelten Eigenschaften werden vollstndig ignoriert, selbst wenn der replacer Parameter verwendet wird.

  • Wenn der Wert eine toJSON()-Methode hat, ist sie dafr verantwortlich zu definieren, welche Daten serialisiert werden. Anstatt dass das Objekt serialisiert wird, wird der Wert, der von der toJSON()-Methode zurckgegeben wird, wenn sie aufgerufen wird, serialisiert. JSON.stringify() ruft toJSON mit einem Parameter auf, dem key, der die gleiche Semantik wie der key-Parameter der replacer Funktion hat:

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

    Alle Temporal-Objekte implementieren die toJSON()-Methode, die eine Zeichenkette zurckgibt (dieselbe wie bei Aufruf von toString()). Daher werden sie als Zeichenketten serialisiert. hnlich implementieren Date-Objekte toJSON(), was dasselbe zurckgibt wie toISOString().

  • Nur enumerable eigene Eigenschaften werden besucht. Dies bedeutet, dass Map, Set, usw. zu "{}" werden. Sie knnen den replacer-Parameter verwenden, um sie in etwas ntzlicheres zu serialisieren.

    Eigenschaften werden mit demselben Algorithmus besucht wie Object.keys(), der eine wohl definierte Ordnung hat und konsistent ber Implementierungen hinweg ist. Zum Beispiel wird JSON.stringify fr dasselbe Objekt immer denselben String erzeugen, und JSON.parse(JSON.stringify(obj)) wrde ein Objekt mit derselben Schlsselreihenfolge wie das Original erzeugen (vorausgesetzt, das Objekt ist vollstndig JSON-serialisierbar).

Der replacer-Parameter

Der replacer-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 bercksichtigt; Symbol-Schlssel werden ignoriert.

Als Funktion nimmt er zwei Parameter an: den key und den value, die stringifiziert werden. Das Objekt, in dem der Schlssel gefunden wurde, wird als this-Kontext des replacer bereitgestellt.

Die replacer-Funktion wird auch fr das ursprnglich stringifizierte Objekt aufgerufen, in welchem Fall der key ein leerer String ("") ist. Anschlieend wird sie fr jede Eigenschaft des Objekts oder Arrays, das stringifiziert wird, aufgerufen. Array-Indizes werden als key in ihrer String-Form bereitgestellt. Der aktuelle Eigenschaftswert wird mit dem Rckgabewert des replacer fr die Stringifizierung ersetzt. Das bedeutet:

• Wenn Sie eine Zahl, eine Zeichenkette, einen booleschen Wert oder null zurckgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Das Zurckgeben eines BigInt wird ebenfalls einen Fehler werfen.)
• Wenn Sie eine Function, ein Symbol oder undefined zurckgeben, wird die Eigenschaft nicht in der Ausgabe enthalten.
• Wenn Sie ein anderes Objekt zurckgeben, wird das Objekt rekursiv stringifiziert, wobei die replacer-Funktion fr jede Eigenschaft aufgerufen wird.

Typischerweise verschieben sich Array-Elemente nie (selbst wenn das Element ein ungltiger Wert wie eine Funktion ist, wird es zu null statt ausgelassen). Mit der replacer-Funktion knnen Sie die Reihenfolge der Array-Elemente steuern, indem Sie ein anderes Array zurckgeben.

Der space-Parameter

Der space-Parameter kann verwendet werden, um Abstnde im finalen String zu steuern.

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

Jede Einrckungsebene wird nie lnger als 10 sein. Zahlenwerte von space 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 JSON
const 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" }, (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

Verwendung einer Funktion als replacer

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 mchten, dass der replacer ein initiales Objekt von einem Schlssel mit einer leeren Zeichenketten-Eigenschaft unterscheidet (da beide den leeren String als Schlssel und mglicherweise ein Objekt als Wert geben wrden), mssen Sie die Iterationsanzahl verfolgen (wenn es ber die erste Iteration hinaus ist, ist es ein echter leerer String-Schlssel).

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 als replacer

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 des space-Parameters

Den Ausgabe-String mit einem Leerzeichen einrcken:

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

Verwendung eines Tabulatorzeichens imitiert das standardmige Formatieren von Text:

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

toJSON()-Verhalten

Die Definition von toJSON() fr ein Objekt ermglicht 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 zirkulren Referenzen

Da das JSON-Format keine Objekt-Referenzen untersttzt (obwohl ein IETF-Entwurf existiert), wird ein TypeError geworfen, wenn versucht wird, ein Objekt mit zirkulren Referenzen zu kodieren.

const circularReference = {};
circularReference.myself = circularReference;

// Serializing circular references throws "TypeError: cyclic object value"
JSON.stringify(circularReference);

Um zirkulre Referenzen zu serialisieren, knnen Sie eine Bibliothek verwenden, die sie untersttzt (z.B. cycle.js von Douglas Crockford) oder eine Lsung selbst implementieren, die das Finden und Ersetzen (oder Entfernen) der zyklischen Referenzen durch serialisierbare Werte erfordert.

Wenn Sie JSON.stringify() verwenden, um ein Objekt tief zu kopieren, mchten Sie stattdessen mglicherweise structuredClone() verwenden, das zirkulre Referenzen untersttzt. JavaScript-Engine-APIs fr die binre Serialisierung, wie v8.serialize(), untersttzen ebenfalls zirkulre Referenzen.

Verwendung von JSON.stringify() mit localStorage

In einem Fall, in dem Sie ein vom Benutzer erstelltes Objekt speichern und es wiederherstellen mchten, auch nachdem der Browser geschlossen wurde, ist das folgende Beispiel ein Modell fr die Anwendbarkeit von JSON.stringify():

// Creating an example of JSON
const 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
const 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, die die well-formed JSON.stringify spec implementieren, werden Lone-Surrogates (beliebiger Codepunkt von U+D800 bis U+DFFF) unter Verwendung von Unicode-Escape-Sequenzen anstelle von wrtlicher Darstellung (Ausgabe von Lone-Surrogates) stringifizieren. Vor dieser nderung konnten solche Zeichenketten nicht in gltigem UTF-8 oder UTF-16 kodiert werden:

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

Aber mit dieser nderung stellt JSON.stringify() Lone-Surrogates unter Verwendung von JSON-Escape-Sequenzen dar, die knnen in gltigem UTF-8 oder UTF-16 kodiert werden:

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

Diese nderung sollte rckwrtskompatibel sein, solange Sie das Ergebnis von JSON.stringify() an APIs wie JSON.parse() bergeben, die jeden gltigen JSON-Text akzeptieren, da sie Unicode-Escapes von Lone-Surrogates als identisch mit den Lone-Surrogates selbst behandeln. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, mssen Sie JSON.stringify()'s zwei mgliche Kodierungen dieser Codepunkte sorgfltig handhaben.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Polyfill of modern JSON.stringify behavior (symbol, well-formed unicode, raw JSON) in core-js
• JSON.parse()
• JSON.rawJSON()