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 Strings und Zahlen, das angibt, welche Eigenschaften von value in die Ausgabe aufgenommen werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Strings oder Zahlen (entweder Primitiven oder Wrapper-Objekte) sind, einschlielich Symbol-Werten, vollstndig ignoriert. Wenn replacer etwas anderes als eine Funktion oder ein Array ist (z.B. null oder nicht bereitgestellt), werden alle string-basierten Eigenschaften des Objekts im resultierenden JSON-String eingeschlossen.

space Optional

Ein String oder eine Zahl, die verwendet wird, um Leerzeichen (einschlielich Einrckungen, Zeilenumbruchzeichen usw.) in den Ausgabe-JSON-String einzufgen, um die Lesbarkeit zu erhhen.

Wenn dies eine Zahl ist, gibt sie die Anzahl der Leerzeichen an, die als Einrckung verwendet werden sollen, begrenzt auf 10 (d.h. jede Zahl grer als 10 wird behandelt, als wre es 10). Werte kleiner als 1 bedeuten, dass kein Leerzeichen verwendet werden soll.

Wenn dies ein String ist, wird der String (oder die ersten 10 Zeichen des Strings, falls er lnger ist) vor jedes verschachtelte Objekt oder Array eingefgt.

Wenn space etwas anderes als ein String oder eine Zahl ist (kann entweder ein Primrwert oder ein Wrapper-Objekt sein) zum Beispiel null oder nicht bereitgestellt wird kein Leerzeichen verwendet.

Rckgabewert

Ein JSON-String, der den gegebenen Wert darstellt, 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 der Wert reprsentiert. Werte werden wie folgt stringifiziert:

• Boolean, Number, String, und BigInt (erhltlich ber Object()) Objekte werden whrend der Stringifizierung gem den traditionellen Konvertierungssemantiken in die entsprechenden primitiven Werte umgewandelt. Symbol Objekte (erhltlich ber Object()) werden als normale 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 Serialisierungsergebnis bereitstellen. Diese Einschrnkung stellt sicher, dass ein ordnungsgemes Serialisierungsverhalten (und sehr wahrscheinlich das begleitende Deserialisierungsverhalten) immer explizit vom Benutzer bereitgestellt wird.
• undefined, Function, und Symbol-Werte sind keine gltigen JSON-Werte. Wenn solche Werte bei der Umwandlung gefunden werden, werden sie entweder weggelassen (wenn sie in einem Objekt gefunden werden) oder in null umgewandelt (wenn sie in einem Array gefunden werden). JSON.stringify() kann undefined zurckgeben, wenn "reine" Werte wie JSON.stringify(() => {}) oder JSON.stringify(undefined) bergeben werden.
• Die Zahlen Infinity und NaN, ebenso wie der Wert null, werden alle als null betrachtet. (Aber im Gegensatz zu den Werten im vorherigen Punkt wrden sie niemals weggelassen.)
• Arrays werden als Arrays serialisiert (umgeben von eckigen Klammern). Nur Array-Indices zwischen 0 und length - 1 (inklusive) werden serialisiert; andere Eigenschaften werden ignoriert.
• Das spezielle rohe JSON-Objekt, das mit JSON.rawJSON() erstellt wurde, wird als der rohe JSON-Text, den es enthlt, serialisiert (indem auf seine rawJSON-Eigenschaft zugegriffen wird).
• Fr andere Objekte:

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

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

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

    Alle Temporal-Objekte implementieren die toJSON()-Methode, die einen String (derselbe wie bei einem Aufruf von toString()) zurckgibt. Somit werden sie als Strings serialisiert. hnlich implementieren Date-Objekte toJSON(), was dasselbe wie toISOString() zurckgibt.

  • Es werden nur enumerable eigene Eigenschaften besucht. Das bedeutet, da 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(), das eine wohl definierte Reihenfolge hat und stabil ber Implementierungen hinweg ist. Zum Beispiel wird JSON.stringify auf demselben Objekt immer denselben String produzieren, und JSON.parse(JSON.stringify(obj)) wrde ein Objekt mit derselben Schlsselreihenfolge wie das Original produzieren (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 in dem Objekt an, die im resultierenden JSON-String enthalten sein sollen. Es werden nur String- und Zahlwerte bercksichtigt; Symbol-Schlssel werden ignoriert.

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

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

• Wenn Sie eine Zahl, einen String, ein Boolean oder null zurckgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Die Rckgabe von BigInt wird ebenfalls einen Fehler werfen.)
• Wenn Sie eine Function, ein Symbol, oder undefined zurckgeben, wird die Eigenschaft nicht in die Ausgabe eingeschlossen.
• Wenn Sie ein anderes Objekt zurckgeben, wird das Objekt rekursiv stringifiziert, wobei die replacer-Funktion auf jede Eigenschaft angewendet wird.

Typischerweise wrde der Index der Array-Elemente niemals verschieben (selbst wenn das Element ein ungltiger Wert wie eine Funktion ist, wird es zu null anstatt weggelassen zu werden). Die Verwendung der replacer-Funktion ermglicht es Ihnen, die Reihenfolge der Array-Elemente zu steuern, indem Sie ein anderes Array zurckgeben.

Der space-Parameter

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

• Wenn es eine Zahl ist, werden aufeinanderfolgende Ebenen in der Stringifizierung jeweils um diese Anzahl von Leerzeichen eingerckt.
• Wenn es ein String ist, werden aufeinanderfolgende Ebenen mit diesem String eingerckt.

Jede Einrckungsebene wird niemals lnger als 10 sein. Zahlwerte von space werden auf 10 begrenzt, und Stringwerte werden auf 10 Zeichen gekrzt.

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 anfngliches Objekt von einem Schlssel mit einer leeren String-Eigenschaft unterscheidet (da beide den leeren String als Schlssel und mglicherweise ein Objekt als Wert geben wrden), mssen Sie die Anzahl der Iterationen verfolgen (wenn es ber die erste Iteration hinausgeht, 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

Rcken Sie die Ausgabe mit einem Leerzeichen ein:

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

Die Verwendung eines Tab-Zeichens ahmt das Standard-Pretty-Print-Aussehen nach:

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

toJSON()-Verhalten

Das Definieren von toJSON() fr ein Objekt erlaubt 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 bei der Serialisierung von zirkulren Referenzen

Da das JSON-Format keine Objektreferenzen untersttzt (obwohl ein IETF-Entwurf existiert), wird ein TypeError ausgelst, 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 diese untersttzt (z.B. cycle.js von Douglas Crockford) oder selbst eine Lsung implementieren, die das Auffinden 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 z.B. v8.serialize(), untersttzen auch zirkulre Referenzen.

Verwendung von JSON.stringify() mit localStorage

In einem Fall, in dem Sie ein vom Benutzer erstelltes Objekt speichern und es wiederherstellen mchten, selbst 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 wohlgeformte JSON.stringify-Spezifikation implementieren, werden einzelne Surrogate (jeder Code-Punkt von U+D800 bis U+DFFF) mit Unicode-Escape-Sequenzen anstelle von buchstblichen (Ausgabe einzelner Surrogate) stringifizieren. Vor dieser nderung konnten solche Strings nicht in gltigem UTF-8 oder UTF-16 kodiert werden:

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

Aber mit dieser nderung reprsentiert JSON.stringify() einzelne Surrogate mit JSON-Escape-Sequenzen, die in gltigem UTF-8 oder UTF-16 kodiert werden knnen:

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 einzelnen Surrogaten als identisch mit den einzelnen Surrogaten selbst behandeln. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, mssen Sie die zwei mglichen Kodierungen dieser Code-Punkte von JSON.stringify() sorgfltig handhaben.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Polyfill des modernen JSON.stringify Verhaltens (Symbol, gut geformtes Unicode, rohes JSON) in core-js
• JSON.parse()
• JSON.rawJSON()