WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

JSON.stringify: JavaScript-Wert als JSON-Text

JSON.stringify serialisiert einen JavaScript-Wert als JSON-Text; ein optionaler Replacer wählt oder verändert Daten und space steuert die Einrückung.

Version: ECMAScript 5 onward; well-formed lone-surrogate escaping from ECMAScript 2019; example target: Node.js 24.22.2

Syntax

JSON.stringify(value[, replacer[, space]])

JSON.stringify(value, replacer?, space?) liefert eine JSON-Zeichenkette oder undefined, wenn der oberste Wert undefined, eine Funktion oder ein Symbol ist. Solche Werte werden in Objekten ausgelassen, in Arrays aber zu null; NaN und Unendlichkeiten werden ebenfalls null, -0 wird als 0 geschrieben. Serialisiert werden eigene aufzählbare Eigenschaften mit Zeichenkettenschlüsseln in der festgelegten Object.keys-Reihenfolge; Symbolschlüssel werden ignoriert. Die Beschreibung eigener aufzählbarer Eigenschaften gilt für die Standardliste; ein Replacer-Array liest benannte Eigenschaften mit Get und kann geerbte oder nicht aufzählbare einschließen.

Eine vorhandene toJSON-Methode läuft vor dem replacer. Eine Replacer-Funktion erhält (key, value), wobei this der Halter ist, und kann den Wert ersetzen oder durch Rückgabe von undefined eine Eigenschaft auslassen; der Wurzelaufruf benutzt den leeren Schlüssel "". Ein Replacer-Array bildet die Zulassungsliste für Objekteigenschaften. Numerisches space ist auf 10 Leerzeichen begrenzt, eine Zeichenkette auf ihre ersten 10 Zeichen. Bei Zeichenketten-space bedeuten „10 Zeichen“ genau die ersten 10 UTF-16-Codeeinheiten.

Eine zyklische Referenz löst TypeError aus. BigInt löst ebenfalls TypeError aus, außer die gewöhnliche Eigenschaftssuche findet ein aufrufbares toJSON; die Methode darf vom Prototyp stammen. Ausnahmen aus Getter, toJSON oder Replacer werden weitergereicht. Stabile Eigenschaftsreihenfolge macht die Ausgabe nicht zu kanonischem JSON für kryptografische Signaturen. Die Methode ist seit ECMAScript 5 Standard; seit ECMAScript 2019 werden einzelne Unicode-Surrogate als Escape-Sequenzen \ud800–\udfff ausgegeben, sodass das Ergebnis wohlgeformtes Unicode ist.

Beispiele

const value = {
  name: "Ada",
  missing: undefined,
  numbers: [1, NaN, Infinity, undefined],
  nested: { keep: true, secret: "hidden" },
};
console.log(JSON.stringify(value, (key, current) =>
  key === "secret" ? undefined : current,
));
console.log(JSON.stringify(undefined) === undefined);

try {
  JSON.stringify(1n);
} catch (error) {
  console.log(error instanceof TypeError);
}

const cycle = {};
cycle.self = cycle;
try {
  JSON.stringify(cycle);
} catch (error) {
  console.log(error instanceof TypeError);
}

Ergebnis

{"name":"Ada","numbers":[1,null,null,null],"nested":{"keep":true}}
true
true
true

Quellen