JSON.stringify()

value

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

replacer Optional

Eine Funktion, die das Verhalten des Stringifizierungsprozesses ändert, oder ein Array von Zeichenfolgen und Zahlen, das die Eigenschaften von value angibt, die in die Ausgabe eingeschlossen werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenfolgen oder Zahlen sind (entweder primitives 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 zeichenfolgenindizierten Eigenschaften des Objekts im resultierenden JSON-String eingeschlossen.

space Optional

Eine Zeichenfolge oder Zahl, die zur Einfügung von Leerzeichen (einschließlich Einrückung, Zeilenumbruchzeichen usw.) in den Ausgabe-JSON-String für bessere Lesbarkeit verwendet wird.

Wenn dies eine Zahl ist, gibt sie die Anzahl der Leerzeichen an, die als Einrückung verwendet werden sollen, wobei sie auf 10 begrenzt ist (d.h. jede Zahl größer als 10 wird behandelt, als wäre sie 10). Werte kleiner als 1 bedeuten, dass keine Leerzeichen verwendet werden sollen.

Wenn dies eine Zeichenfolge ist, 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 (entweder ein primitives oder ein Wrapper-Objekt) - zum Beispiel null oder nicht angegeben - werden keine Leerzeichen verwendet.

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

TypeError

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

• value enthält einen zyklischen Verweis.
• Ein BigInt-Wert wird angetroffen.

JSON.stringify() wandelt einen Wert in die JSON-Notation um, die den Wert darstellt. Werte werden folgendermaßen stringifiziert:

• Boolean, Number, String und BigInt (erhältlich über Object()) Objekte werden während der Stringifizierung in die entsprechenden primitiven Werte umgewandelt, gemäß der traditionellen Konversionssemantik. Symbol-Objekte (erhältlich über Object()) werden als normale Objekte behandelt.

• Der Versuch, BigInt-Werte zu serialisieren, wird scheitern. Hat der BigInt jedoch eine toJSON()-Methode (durch Monkey Patching: BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsergebnis liefern. Diese Einschränkung stellt sicher, dass immer ein korrektes Serialisierungsverhalten (und sehr wahrscheinlich auch das entsprechende Deserialisierungsverhalten) explizit vom Benutzer bereitgestellt wird.

• undefined, Function und Symbol-Werte sind keine gültigen JSON-Werte. Sollte ein solcher Wert während der Umwandlung angetroffen werden, wird er entweder weggelassen (wenn im Objekt gefunden) oder in null geändert (wenn im Array gefunden). JSON.stringify() kann undefined zurückgeben, wenn "pure" Werte wie JSON.stringify(() => {}) oder JSON.stringify(undefined) übergeben werden.

• Die Zahlen Infinity und NaN, sowie der Wert null, werden alle als null betrachtet. (Im Gegensatz zu den Werten des vorherigen Punktes, würden diese jedoch nie weggelassen.)

• 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 rohe JSON-Objekt, das mit JSON.rawJSON() erstellt wurde, wird als der rohe JSON-Text serialisiert, den es enthält (durch Zugriff auf seine rawJSON-Eigenschaft).

• Für andere Objekte:

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

  • Hat der Wert eine toJSON()-Methode, ist es verantwortlich, welche Daten serialisiert werden. Anstatt das Objekt zu serialisieren, wird der Wert, der von der toJSON()-Methode zurückgegeben wird, serialisiert. JSON.stringify() ruft toJSON mit einem Parameter key auf, der den gleichen semantischen Wert 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 dieses Objekt angewendet wird, eine leere Zeichenfolge

    Alle Temporal-Objekte implementieren die toJSON()-Methode, die eine Zeichenfolge (gleich dem Aufruf von toString()) zurückgibt. Daher werden sie als Zeichenfolgen serialisiert. Ebenso implementieren Date-Objekte toJSON(), das dasselbe wie toISOString() zurückgibt.

  • Es werden nur enumerable own properties 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 dem gleichen Algorithmus wie Object.keys() besucht, der eine wohldefinierte Reihenfolge hat und implementierungsübergreifend stabil ist. Zum Beispiel wird JSON.stringify auf demselben Objekt immer denselben String produzieren, und JSON.parse(JSON.stringify(obj)) würde ein Objekt mit derselben Schlüsselreihenfolge wie das Original produzieren (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 in den resultierenden JSON-String aufgenommen werden sollen. Nur Zeichenketten- und Zahlenwerte werden berücksichtigt; Symbolschlüssel werden ignoriert.

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

Die replacer-Funktion wird auch für das initial stringifizierte Objekt aufgerufen, in welchem Fall der key eine leere Zeichenfolge ("") ist. Anschließend wird sie für jede Eigenschaft des Objekts oder Arrays aufgerufen, das stringifiziert wird. Array-Indizes werden in ihrer Zeichenform als key bereitgestellt. Der aktuelle Eigenschaftswert wird durch den Rückgabewert der replacer-Funktion für die Stringifizierung ersetzt. Das bedeutet:

• Wenn Sie eine Zahl, Zeichenkette, boolean oder null zurückgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Die Rückgabe eines BigInt löst ebenfalls einen Fehler aus.)
• Wenn Sie eine Function, Symbol oder undefined zurückgeben, wird die Eigenschaft in der Ausgabe nicht enthalten.
• Wenn Sie ein anderes Objekt zurückgeben, wird das Objekt rekursiv stringifiziert, indem die replacer-Funktion auf jede Eigenschaft angewendet wird.

Typischerweise würde sich der Index von Array-Elementen niemals verschieben (selbst wenn das Element ein ungültiger Wert wie eine Funktion ist, wird es null statt ausgelassen). Die Verwendung der replacer-Funktion erlaubt die Kontrolle der Reihenfolge der Array-Elemente, indem ein unterschiedliches Array zurückgegeben wird.

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

• Wenn es eine Zahl ist, werden aufeinanderfolgende Ebenen der Stringifizierung jeweils durch diese Anzahl an Leerzeichen eingerückt.
• Wenn es eine Zeichenkette ist, werden aufeinanderfolgende Ebenen durch diese Zeichenkette eingerückt.

Jede Ebene der Einrückung wird niemals länger als 10 sein. Zahlenwerte von space werden auf 10 begrenzt, und Zeichenfolgenwerte werden 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 Zeichenkettens-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 sie über der ersten Iteration liegt, handelt es sich um einen echten leeren 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}"

Indizieren Sie die Ausgabe mit einem Leerzeichen:

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

Durch die Verwendung eines Tab-Zeichens wird das Erscheinungsbild eines Standard-Pretty-Prints imitiert:

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

Das Definieren 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-Draft existiert), wird ein TypeError ausgelöst, wenn man versucht, ein Objekt mit zyklischen Referenzen zu kodieren.

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

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

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

Wenn Sie JSON.stringify() verwenden, um ein Objekt tiefgreifend zu kopieren, möchten Sie stattdessen möglicherweise structuredClone() verwenden, das zyklische Referenzen unterstützt. JavaScript-Engine-APIs zur binären Serialisierung, wie v8.serialize(), unterstützen ebenfalls zyklische Referenzen.

In einem Fall, in dem Sie ein vom Benutzer erstelltes Objekt speichern und es auch nach dem Schließen des Browsers wiederherstellen möchten, 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-Spezifikation implementieren, werden einzelne Surrogate (jedes Codepunkt von U+D800 bis U+DFFF) mit Unicode-Escape-Sequenzen anstelle von wörtlichen Surrogaten stringifizieren. Vor dieser Änderung konnten solche Zeichenfolgen nicht in gültigem UTF-8 oder UTF-16 codiert werden:

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

Mit dieser Änderung stellt JSON.stringify() einzelne Surrogate mit JSON-Escape-Sequenzen dar, die in gültigem UTF-8 oder UTF-16 codiert 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 einzelner Surrogate als identisch mit den einzelnen Surrogaten selbst behandeln. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, müssen Sie JSON.stringify()s zwei mögliche Codierungen dieser Codepunkte sorgfältig handhaben.

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