JSON.stringify()

value

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

replacer Optional

Eine Funktion, die das Verhalten des Stringifizierungsprozesses verändert, oder ein Array von Zeichenketten und Zahlen, die die Eigenschaften von value spezifizieren, die in das Ausgabeergebnis eingefügt werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenketten oder Zahlen sind (entweder primitive oder Wrapper-Objekte), einschließlich Symbol-Werten, vollständig 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 (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 als 10 wird behandelt, als ob sie 10 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.

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.

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

TypeError

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

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

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

• Boolean, Number, String, und BigInt (erreichbar über Object()) Objekte werden während 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 Einschränkung stellt sicher, dass vom Benutzer immer explizit ein korrektes Serialisierungs- (und sehr wahrscheinlich das dazugehörige Deserialisierungs-)Verhalten bereitgestellt wird.
• undefined, Function, und Symbol-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 in null geändert (wenn sie in einem Array gefunden werden). JSON.stringify() kann undefined zurückgeben, 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, würden sie niemals ausgelassen.)
• Arrays werden als Arrays (eingeschlossen in eckige Klammern) serialisiert. Nur Array-Indizes zwischen 0 und length - 1 (einschließlich) 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 enthält (durch den Zugriff auf seine rawJSON-Eigenschaft).
• Für andere Objekte:

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

  • Wenn der Wert eine toJSON()-Methode hat, ist sie dafür verantwortlich zu definieren, welche Daten serialisiert werden. Anstatt dass das Objekt serialisiert wird, wird der Wert, der von der toJSON()-Methode zurückgegeben 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 zurückgibt (dieselbe wie bei Aufruf von toString()). Daher werden sie als Zeichenketten serialisiert. Ähnlich implementieren Date-Objekte toJSON(), was dasselbe zurückgibt wie toISOString().

  • Nur enumerable eigene Eigenschaften werden besucht. Dies bedeutet, dass Map, Set, usw. zu "{}" werden. Sie können den replacer-Parameter verwenden, um sie in etwas nützlicheres 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 für dasselbe Objekt immer denselben String erzeugen, und JSON.parse(JSON.stringify(obj)) würde ein Objekt mit derselben Schlüsselreihenfolge wie das Original erzeugen (vorausgesetzt, das Objekt ist vollständig JSON-serialisierbar).

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 berücksichtigt; Symbol-Schlüssel werden ignoriert.

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

Die replacer-Funktion wird auch für das ursprünglich stringifizierte Objekt aufgerufen, in welchem Fall der key ein leerer String ("") ist. Anschließend wird sie für 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 Rückgabewert des replacer für die Stringifizierung ersetzt. Das bedeutet:

• Wenn Sie eine Zahl, eine Zeichenkette, einen booleschen Wert oder null zurückgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Das Zurückgeben eines BigInt wird ebenfalls einen Fehler werfen.)
• Wenn Sie eine Function, ein Symbol oder undefined zurückgeben, wird die Eigenschaft nicht in der Ausgabe enthalten.
• Wenn Sie ein anderes Objekt zurückgeben, wird das Objekt rekursiv stringifiziert, wobei die replacer-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 zu null statt ausgelassen). Mit der replacer-Funktion können Sie die Reihenfolge der Array-Elemente steuern, indem Sie ein anderes Array zurückgeben.

Der space-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 von space werden auf 10 begrenzt, und Zeichenkettenwerte werden auf 10 Zeichen abgeschnitten.

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 der replacer 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}"

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
}
*/

Die Definition von toJSON() 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'"]'

Da das JSON-Format keine Objekt-Referenzen unterstützt (obwohl ein IETF-Entwurf existiert), wird ein TypeError 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 Sie JSON.stringify() verwenden, um ein Objekt tief zu kopieren, möchten Sie stattdessen möglicherweise structuredClone() verwenden, das zirkuläre Referenzen unterstützt. JavaScript-Engine-APIs für die binäre Serialisierung, wie v8.serialize(), unterstützen ebenfalls zirkuläre Referenzen.

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 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);

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 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 stellt JSON.stringify() Lone-Surrogates unter Verwendung von JSON-Escape-Sequenzen dar, die kö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 von JSON.stringify() an APIs wie JSON.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 von JSON.stringify() direkt interpretieren, müssen Sie JSON.stringify()'s zwei mögliche Kodierungen dieser Codepunkte sorgfältig handhaben.

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