JSON.stringify()

value

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

replacer Optional

Eine Funktion, die das Verhalten des Stringifizierungsvorgangs ändert, oder ein Array von Strings und Zahlen, das die Eigenschaften von value angibt, die in die Ausgabe aufgenommen werden sollen. Wenn replacer ein Array ist, werden alle Elemente in diesem Array, die keine Strings 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 string-beschlüsselten Eigenschaften des Objekts in den resultierenden JSON-String aufgenommen.

space Optional

Ein String oder eine Zahl, die verwendet wird, um Leerzeichen (einschließlich Einrückungen, Zeilenumbrüche usw.) in den Ausgabe-JSON-String für Lesbarkeitszwecke einzufügen.

Wenn dies eine Zahl ist, 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 so behandelt, als wäre sie 10). Werte kleiner als 1 bedeuten, dass keine Leerzeichen verwendet werden sollen.

Wenn dies ein String ist, wird der String (oder die ersten 10 Zeichen des Strings, wenn er länger ist) vor jedem verschachtelten Objekt oder Array eingefügt.

Wenn space etwas anderes als ein String oder eine 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 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() konvertiert einen Wert in die von dem Wert dargestellte JSON-Notation. Werte werden auf folgende Weise stringifiziert:

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

• Der Versuch, BigInt-Werte zu serialisieren, führt zu einem Fehler. Wenn das BigInt jedoch eine toJSON()-Methode hat (durch Monkey-Patching: BigInt.prototype.toJSON = ...), kann diese Methode das Serialisierungsergebnis bereitstellen. Diese Einschränkung stellt sicher, dass immer ein richtiges Serialisierungsverhalten (und sehr wahrscheinlich das zugehörige Deserialisierungsverhalten) explizit vom Benutzer bereitgestellt wird.

• undefined, Function und Symbol-Werte sind keine gültigen JSON-Werte. Wenn während der Konvertierung solche Werte 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 vorherigen Punkt würden sie nie 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 rohe JSON-Objekt, das mit JSON.rawJSON() erstellt wird, wird als der rohe JSON-Text serialisiert, den es enthält (durch Zugriff auf seine rawJSON-Eigenschaft).

• Für andere Objekte:

  • Alle Symbol-schlüsseligen Eigenschaften werden komplett ignoriert, selbst wenn der replacer Parameter verwendet wird.

  • Wenn der Wert eine toJSON()-Methode besitzt, ist sie dafür verantwortlich, zu definieren, welche Daten serialisiert werden. Stattdessen wird der Wert, der zurückgegeben wird, wenn die toJSON()-Methode 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 Eigenname der Eigenschaft
    • 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 einen String zurückgibt (dieselbe wie der Aufruf von toString()). Daher werden sie als Strings serialisiert. Ebenso implementieren Date-Objekte toJSON(), was denselben Wert wie toISOString() zurückgibt.

  • 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 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 erzeugen, und JSON.parse(JSON.stringify(obj)) würde ein Objekt mit derselben Schlüsselanordnung 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. Nur String- und Zahlenwerte werden berücksichtigt; Symbol-Schlüssel werden ignoriert.

Als Funktion nimmt es zwei Parameter: den key und den value, die gerade 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üngliche Objekt aufgerufen, das stringifiziert wird, in welchem Fall der key ein leerer String ("") ist. Danach wird sie für jede Eigenschaft des Objekts oder Arrays aufgerufen, das stringifiziert wird. Array-Indizes werden in ihrer String-Form 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, einen String, einen Boolean oder null zurückgeben, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet. (Das Zurückgeben eines BigInt führt ebenfalls zu einem Fehler.)
• 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.

Normalerweise würde sich der Index von Array-Elementen niemals verschieben (selbst wenn das Element ein ungültiger Wert wie eine Funktion ist, wird es statt ausgelassen zu null). 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 finalen String zu steuern.

• Wenn es eine Zahl ist, werden aufeinanderfolgende Ebenen während der Stringifizierung durch diese Anzahl von Leerzeichen eingerückt.
• Wenn es ein String ist, werden aufeinanderfolgende Ebenen durch diesen String eingerückt.

Jede Einrückungsstufe wird niemals länger als 10 Zeichen sein. Zahlenwerte von space werden auf 10 begrenzt und String-Werte 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 ursprüngliches Objekt von einem Schlüssel mit einer leeren Eigenschaft unterscheidet (da beide den leeren String als Schlüssel und möglicherweise ein Objekt als Wert ergeben würden), müssen Sie die Anzahl der Iterationen verfolgen (wenn sie über der ersten Iteration liegt, 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}"

Rücken Sie die Ausgabe mit einem Leerzeichen ein:

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

Die Verwendung eines Tabulatorzeichens imitiert das Standardaussehen von Pretty-Print:

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 des 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 Objektverweise unterstützt (obwohl ein IETF-Entwurf existiert), wird ein TypeError ausgelöst, wenn versucht wird, 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 Auffinden 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 vielleicht 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 von Ihrem Benutzer erstelltes Objekt speichern möchten und es ermöglichen wollen, dass es auch nach dem Schließen des Browsers wiederhergestellt wird, 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 spezielle wohlgeformte JSON.stringify Spezifikation implementieren, werden Einzelsurrogate (jedes Codepunkt von U+D800 bis U+DFFF) mit Unicode-Escape-Sequenzen anstelle wörtlich stringifizieren (Ausgabe von Einzelsurrogaten). 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() Einzelsurrogate unter Verwendung von JSON-Escape-Sequenzen dar, die in gültigem 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 Einzelsurrogaten als identisch zu den Einzelsurrogaten selbst behandeln werden. Nur wenn Sie das Ergebnis von JSON.stringify() direkt interpretieren, müssen Sie JSON.stringify()'s zwei mögliche Kodierungen dieser Codepunkte sorgfältig behandeln.

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