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 einbezogen werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Zeichenfolgen oder Zahlen (entweder primitive oder Wrapper-Objekte) sind, einschließlich Symbol-Werte, vollständig ignoriert. Wenn replacer kein Array oder eine Funktion ist (z.B. null oder nicht angegeben), werden alle mit Zeichenfolgen versehenen Eigenschaften des Objektes in den resultierenden JSON-String einbezogen.

space Optional

Eine Zeichenfolge oder Zahl, die zum Einfügen von Leerzeichen (einschließlich Einrückungen, Zeilenumbrüche usw.) in den Ausgabestring zur besseren Lesbarkeit verwendet wird.

Wenn dies eine Zahl ist, gibt sie die Anzahl der Leerzeichen an, die für Einrückungen verwendet werden sollen; sie ist auf maximal 10 begrenzt (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 es eine Zeichenfolge ist, wird die Zeichenfolge (oder die ersten 10 Zeichen, wenn sie länger ist) vor jedes geschachtelte Objekt oder Array eingefügt.

Wenn space weder eine Zeichenfolge noch eine Zahl ist (kann entweder ein primitiver Wert oder ein Wrapper-Objekt sein) — 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 Zirkularverweis.
• Ein BigInt-Wert wird entdeckt.

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

• Boolean, Number, String und BigInt (erreichbar über Object()) Objekte werden in die entsprechenden primitiven Werte während der Stringifizierung umgewandelt, in Übereinstimmung mit den traditionellen Konversionssemantiken. Symbol Objekte (erreichbar über Object()) werden als gewöhnliche Objekte behandelt.

• Ein Versuch, BigInt-Werte zu serialisieren, wird einen Fehler auslösen. Wenn das BigInt jedoch eine toJSON()-Methode hat (durch Ändern des Prototyps: BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsergebnis bereitstellen. Diese Einschränkung stellt sicher, dass ein geeignetes 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 solch ein Wert während der Konvertierung angetroffen wird, werden sie entweder weggelassen (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 bei "rein" Werten wie JSON.stringify(() => {}) oder JSON.stringify(undefined) eingereicht wird.

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

• Arrays werden als Arrays serialisiert (in eckige Klammern eingeschlossen). Nur die 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 Eigenschaften, die durch Symbol-Schlüssel gekennzeichnet sind, werden vollständig ignoriert, selbst beim Verwenden des replacer Parameters.

  • Wenn der Wert eine toJSON()-Methode hat, ist diese dafür verantwortlich, zu definieren, welche Daten serialisiert werden. Anstatt das Objekt zu serialisieren, wird der Wert, der von der toJSON()-Methode bei einem Aufruf zurückgegeben wird, serialisiert. JSON.stringify() ruft toJSON mit einem Parameter, dem key, auf, der die gleiche Bedeutung 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 Zeichenfolge
    • wenn JSON.stringify() direkt auf diesem Objekt aufgerufen wurde, eine leere Zeichenfolge

    Alle Temporal-Objekte implementieren die toJSON()-Methode, die eine Zeichenfolge zurückgibt (wie der Aufruf von toString()). Somit werden sie als Zeichenfolgen serialisiert. Ähnlich implementieren Date-Objekte toJSON(), das gleiches Ergebnis wie toISOString() zurückgibt.

  • Es werden nur enumerable eigene Eigenschaften besucht. Dies bedeutet, dass Map, Set, etc. zu "{}" werden. Sie können den replacer Parameter verwenden, um sie zu etwas nützlicherem zu serialisieren.

    Eigenschaften werden unter Verwendung des gleichen Algorithmus wie Object.keys() durchlaufen, der eine gut definierte Reihenfolge hat und über Implementierungen hinweg stabil ist. Zum Beispiel würde das Aufrufen von JSON.stringify auf demselben Objekt immer den gleichen 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 sollen. Es werden nur Zeichenfolgen und Zahlen beachtet; Symbolschlü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 anfängliche Objekt aufgerufen, das stringifiziert wird, wobei der key eine leere Zeichenfolge ("") ist. Sie wird dann für jede Eigenschaft im Objekt oder Array aufgerufen, das stringifiziert wird. Array-Indizes werden in ihrer Zeichenform als key angegeben. Der aktuelle Eigenschaftswert wird durch den Rückgabewert von replacer für die Stringifizierung 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, Symbol, oder undefined zurückgeben, wird die Eigenschaft nicht in die Ausgabe einbezogen.
• 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 die Indizes der Arrayelemente nie verschieben (selbst wenn das Element ein ungültiger Wert wie eine Funktion ist, wird es zu null anstatt weggelassen zu werden). 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 es sich um eine Zahl handelt, wird jede nachfolgende Ebene beim Stringifizieren um so viele Leerzeichen eingerückt.
• Wenn es sich um eine Zeichenfolge handelt, werden nachfolgende Ebenen um diese Zeichenfolge eingerückt.

Jede Einrückungsebene wird nie länger als 10 sein. Zahlenwerte von space werden auf 10 begrenzt, und Zeichenfolgen 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 anfängliches Objekt von einem Schlüssel mit einer Eigenschaft eines leeren Strings unterscheidet (da beide den leeren String als Schlüssel und potenziell ein Objekt als Wert ergeben würden), müssen Sie die Anzahl der Iterationen nachverfolgen (wenn es über die erste Iteration hinausgeht, handelt es sich um einen echten leeren Zeichenfolgenschlü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 Tabulators imitiert das standardmäßige Pretty-Print-Erscheinungsbild:

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 Objektverweise nicht unterstützt (obwohl ein IETF-Entwurf existiert), wird ein TypeError ausgelöst, wenn versucht wird, ein Objekt mit Zirkularverweisen zu kodieren.

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

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

Um Zirkularverweise zu serialisieren, können Sie eine Bibliothek verwenden, die dies unterstützt (z.B. cycle.js von Douglas Crockford) oder eine eigene Lösung implementieren, die erfordert, dass die zyklischen Verweise durch serialisierbare Werte gefunden und ersetzt (oder entfernt) werden.

Wenn Sie JSON.stringify() zum tiefenkopieren eines Objekts verwenden möchten, sollten Sie stattdessen structuredClone() verwenden, das Zirkularreferenzen unterstützt. JavaScript-Engine-APIs für die binäre Serialisierung, wie zum Beispiel v8.serialize(), unterstützen ebenfalls Zirkularreferenzen.

Wenn Sie ein Objekt speichern möchten, das von Ihrem Benutzer erstellt wurde, 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 wohlgeformte JSON.stringify-Spezifikation implementieren, werden einzelne Surrogate (jedes Codepunkt von U+D800 bis U+DFFF) unter Verwendung von Unicode-Escape-Sequenzen anstatt wörtlich (Ausgabe einzelner Surrogate) stringifizieren. Vor dieser Änderung konnten solche Strings nicht in gültigem UTF-8 oder UTF-16 kodiert werden:

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

Mit dieser Änderung stellt JSON.stringify() einzelne Surrogate mit 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 einzelnen Surrogaten als identisch mit den Surrogaten selbst behandeln. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, müssen Sie sorgfältig die zwei möglichen Codierungen dieser Codepunkte durch JSON.stringify() behandeln.

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