JSON.stringify()

value

Der zu konvertierende Wert in einen JSON-String.

replacer Optional

Eine Funktion, die das Verhalten des Stringifizierungsprozesses verändert, oder ein Array aus Zeichenfolgen und Zahlen, das die Eigenschaften von value spezifiziert, die in der Ausgabe enthalten sein sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenfolgen oder Zahlen sind (entweder primitive oder Wrapper-Objekte), einschließlich Symbol-Werte, komplett ignoriert. Wenn replacer etwas anderes als eine Funktion oder ein Array ist (z.B. null oder nicht bereitgestellt), werden alle string-bezogenen Eigenschaften des Objekts im resultierenden JSON-String enthalten.

space Optional

Eine Zeichenfolge oder Zahl, die verwendet wird, um Leerzeichen (einschließlich Einrückungen, Zeilenumbrüche etc.) in den ausgegebenen JSON-String einzufügen, um die Lesbarkeit zu erhöhen.

Ist dies eine Zahl, gibt sie die Anzahl der Leerzeichen an, die als Einrückung verwendet werden sollen, begrenzt auf 10 (das heißt, jede Zahl größer als 10 wird behandelt, als wäre sie 10). Werte kleiner als 1 bedeuten, dass kein Leerzeichen verwendet werden soll.

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

Wenn space etwas anderes als eine Zeichenfolge oder Zahl ist (kann entweder ein Primitiv oder ein Wrapper-Objekt sein) — z.B. null oder nicht bereitgestellt — werden keine Leerzeichen verwendet.

Ein JSON-String, der den gegebenen Wert darstellt, 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 darstellt. Werte werden auf folgende Weise stringifiziert:

• Boolean, Number, String und BigInt (erreichbar über Object()) Objekte werden während des Stringifizierens in die entsprechenden primitiven Werte konvertiert, gemäß der traditionellen Konvertierungssemantik. Symbol-Objekte (erreichbar über Object()) werden als einfache Objekte behandelt.

• Der Versuch, BigInt-Werte zu serialisieren, wird einen Fehler auslösen. Hat das BigInt jedoch eine toJSON()-Methode (durch Monkey Patching: BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsergebnis liefern. Diese Einschränkung stellt sicher, dass ein ordnungsgemäßes Serialisierungsverhalten (und sehr wahrscheinlich das zugehörige Deserialisierungsverhalten) immer explizit vom Benutzer 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 sich in einem Objekt befinden) oder in null geändert (wenn sie in einem Array gefunden werden). JSON.stringify() kann undefined zurückgeben, wenn "reine" Werte wie JSON.stringify(() => {}) oder JSON.stringify(undefined) übergeben werden.

• Die Zahlen Infinity und NaN sowie der Wert null werden alle als null betrachtet. (Aber im Gegensatz zu den Werten im vorherigen Punkt werden sie niemals ausgelassen.)

• Arrays werden als Arrays serialisiert (eingeschlossen in eckige Klammern). Nur Array-Indizes zwischen 0 und length - 1 (einschließlich) werden serialisiert; andere Eigenschaften werden ignoriert.

• Das spezielle Roh-JSON-Objekt, das mit JSON.rawJSON() erstellt wurde, wird als das rohe JSON-Text serialisiert, das es enthält (durch Zugriff auf seine rawJSON-Eigenschaft).

• Für andere Objekte:

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

  • Wenn der Wert eine toJSON()-Methode hat, ist es verantwortlich zu definieren, welche Daten serialisiert werden. Anstelle des Objekts wird der Wert serialisiert, der von der toJSON()-Methode zurückgegeben wird, wenn sie aufgerufen wird. JSON.stringify() ruft toJSON mit einem Parameter auf, dem key, welcher dieselben Semantiken wie der key-Parameter der replacer-Funktion hat:

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

    Alle Temporal-Objekte implementieren die toJSON()-Methode, die eine Zeichenfolge zurückgibt (dieselbe wie ein Aufruf von toString()). Daher werden sie als Zeichenfolgen serialisiert. Ähnlich implementieren Date-Objekte toJSON(), was dasselbe zurückgibt wie toISOString().

  • Es werden nur zählbare eigenen Eigenschaften besucht. Das bedeutet, Map, Set usw. werden zu "{}". 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 gut definierte Reihenfolge hat und stabil über Implementationen hinweg ist. Zum Beispiel wird JSON.stringify auf demselben Objekt immer denselben String erzeugen, und JSON.parse(JSON.stringify(obj)) würde ein Objekt mit derselben Schlüsselfolge wie das Original erzeugen (vorausgesetzt, dass das Objekt komplett JSON-serialisierbar ist).

Der replacer Parameter kann entweder eine Funktion oder ein Array sein.

Als Array geben seine Elemente die Namen der Eigenschaften des Objekts an, die im resultierenden JSON-String enthalten sein sollen. Nur Zeichenfolgen und Zahlenwerte werden berücksichtigt; Symbol-Schlüssel werden ignoriert.

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

Die replacer Funktion wird auch für das initial zu stringifizierende Objekt aufgerufen, in diesem Fall ist der key ein leerer String (""). Sie wird dann für jede Eigenschaft auf dem Objekt oder Array, das stringifiziert wird, aufgerufen. Array-Indizes werden in ihrer Zeichenform als key bereitgestellt. Der aktuelle Eigenschaftswert wird für die Stringifizierung durch den Rückgabewert des replacer ersetzt. Das bedeutet:

• Wenn Sie eine Zahl, Zeichenfolge, Boolean oder null zurückgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Das Zurückgeben eines BigInt wird ebenfalls einen Fehler auslösen.)
• Wenn Sie eine Function, ein Symbol oder undefined zurückgeben, wird die Eigenschaft nicht in die Ausgabe aufgenommen.
• Wenn Sie ein anderes Objekt zurückgeben, wird das Objekt rekursiv stringifiziert, wobei die replacer Funktion auf jede Eigenschaft aufgerufen wird.

Typischerweise würden sich Array-Elemente nicht verschieben (auch wenn das Element ein ungültiger Wert wie eine Funktion ist, wird es null statt ausgelassen). Die Verwendung der replacer Funktion ermöglicht es Ihnen, die Reihenfolge der Array-Elemente zu steuern, indem Sie ein anderes Array zurückgeben.

Der space Parameter kann verwendet werden, um den Abstand im endgültigen String zu steuern.

• Wenn er eine Zahl ist, wird jede nachfolgende Ebene in der Stringifizierung um diese Anzahl von Leerzeichen eingezogen.
• Wenn er eine Zeichenfolge ist, werden nachfolgende Ebenen mit dieser Zeichenfolge eingezogen.

Jede Einrückungsebene wird niemals länger als 10 sein. Zahlwerte von space sind auf 10 begrenzt, und Zeichenfolgenwerte sind auf 10 Zeichen gekürzt.

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 Zeichenfolge unterscheidet (da beide die leere Zeichenfolge als Schlüssel geben würden und potenziell ein Objekt als Wert), müssen Sie die Anzahl der Iterationen verfolgen (wenn es über die erste Iteration hinausgeht, ist es ein echter leerer Zeichenfolgeschlü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}"

Rücken Sie die Ausgabe mit einem Leerzeichen ein:

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

Die Verwendung eines Tab-Zeichens ahmt ein standardmäßiges hübsch bedrucktes Erscheinungsbild nach:

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

Die Definition von toJSON() für ein Objekt ermöglicht das Überschreiben seines Serialisierungsverhaltens.

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 Objektreferenzen unterstützt (obwohl ein IETF-Entwurf existiert), wird ein TypeError ausgelöst, 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 es erfordert, die zyklischen Referenzen durch serialisierbare Werte zu finden und zu ersetzen (oder zu entfernen).

Wenn Sie JSON.stringify() verwenden, um ein Objekt tief zu kopieren, möchten Sie stattdessen vielleicht 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.

Falls Sie ein vom Benutzer erstelltes Objekt speichern und es wiederherstellen möchten, selbst 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 wohlgeformte JSON.stringify-Spezifikation implementieren, werden alleinstehende Surrogates (jedes Code-Punkt von U+D800 bis U+DFFF) unter Verwendung von Unicode-Escape-Sequenzen anstatt buchstäblich (Ausgabe von alleinstehenden Surrogates) stringifizieren. Vor dieser Änderung konnten solche Zeichenfolgen nicht in gültigem UTF-8 oder UTF-16 kodiert werden:

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

Aber mit dieser Änderung stellt JSON.stringify() alleinstehende Surrogates unter Verwendung von JSON-Escape-Sequenzen dar, die in validem UTF-8 oder UTF-16 kodiert werden können:

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 alleinstehenden Surrogates genauso behandeln wie die alleinstehenden Surrogates selbst. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, müssen Sie die beiden möglichen Kodierungen dieser Code-Punkte von JSON.stringify() sorgfältig handhaben.

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