JSON.stringify()

Die JSON.stringify() Methode konvertiert einen JavaScript-Wert in einen JSON-String. Optional werden Werte ersetzt, wenn eine Ersetzungsfunktion angegeben ist. Optional werden nur die angegebenen Eigenschaften einbezogen, wenn ein Ersetzungsarray angegeben ist.

Syntax

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

Parameter

value
Der Wert, der zu einem JSON-String konvertiert werden soll.
replacer Optional
Eine Funktion, die das Verhalten des String- Erstellungsprozesses ver├Ąndert, oder ein Array von String und Number Objekten, die als Whiteliste f├╝r die Selektion von Eigenschaften des value Objektes fungiert, um nur bestimmte Eigenschaften im JSON-String aufzunehmen. Wenn dieser Parameter null ist oder nicht unterst├╝tzt wird, werden alle Eigenschaften des Objektes im JSON-String aufgenommen.
space Optional
Ein String oder Number Objekt, welches eingesetzt wird, um Whitespaces in den JSON-String f├╝r die Lesbarkeit hinzuzuf├╝gen. Wenn eine Number angegeben ist, bedeutet dies, dass die angegebene Anzahl an Leerzeichen hinzugef├╝gt werden; Die Anzahl der Leerzeichen ist hierbei auf 10 begrenzt und wird bei einer gr├Â├čeren Anzahl auf 10 gesetzt. Werte kleiner als 1 bedeuten, dass keine Leerzeichen verwendet werden sollen. Wenn ein String angegeben wird, wird der String (oder die ersten 10 Zeichen des Strings, wenn er l├Ąnger ist) als Leerzeichen benutzt. Wenn dieser Parameter null ist oder nicht unterst├╝tzt wird, werden keine Whitespaces verwendet.

R├╝ckgabewert

Ein JSON-String, der den angegebenen Wert repr├Ąsentiert.

Fehler

Erzeugt einen TypeError ("cyclic object value") Fehler, wenn eine zyklische Referenz gefunden wird.

Beschreibung

JSON.stringify() konvertiert einen Wert in einen in JSON-Notation gleichwertigen Wert:

  • Wenn der Wert eine toJSON() Methode hat, definiert diese, welche Daten serialisiert werden.
  • Boolean, Number und String Objekte werden zu den entsprechenden primitiven Werten, gem├Ą├č der traditionellen Konvertierungssemantik, konvertiert.
  • Wenn undefined, eine Funktion oder ein Symbol w├Ąhrend der Konvertierung auftritt, wird es einfach weggelassen (wenn es in einem Objekt gefunden wird) oder zu null ge├Ąndert (wenn es in einem Array gefunden wurde). JSON.stringify kann undefined zur├╝ckgeben, wenn nur ein Wert wie JSON.stringify(function(){}) or JSON.stringify(undefined) ├╝bergeben wird.
  • Alle Symbol-Schl├╝ssel-Eigenschaften werden komplett ignoriert, auch wenn die replacer Funktion genutzt wird.
  • Instanzen von Date implementieren die toJSON() Funktion so, dass ein String (der gleich wie bei date.toISOString() ist) zur├╝ckgibt. Daher werden sie als String behandelt.
  • Die Zahlen Infinity und NaN genauso wie null Objekte werden zu null umgewandelt.
  • F├╝r alle anderen Object Instanzen (eingeschlossen Map, Set, WeakMap und WeakSet) werden nur die aufz├Ąhlbaren (enumerable) Eigenschaften serialisiert.
JSON.stringify({});                    // '{}'
JSON.stringify(true);                  // 'true'
JSON.stringify('foo');                 // '"foo"'
JSON.stringify([1, 'false', false]);   // '[1,"false",false]'
JSON.stringify([NaN, null, Infinity]); // '[null,null,null]'
JSON.stringify({ x: 5 });              // '{"x":5}'

JSON.stringify(new Date(2006, 0, 2, 15, 4, 5))
// '"2006-01-02T15:04:05.000Z"'

JSON.stringify({ x: 5, y: 6 });
// '{"x":5,"y":6}' or '{"y":6,"x":5}'
JSON.stringify([new Number(1), new String('false'), new Boolean(false)]);
// '[1,"false",false]'

JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] });
// '{"x":[10,null,null,null]}'

// Standard-Datenstrukturen
JSON.stringify([new Set([1]), new Map([[1, 2]]), new WeakSet([{a: 1}]), new WeakMap([[{a: 1}, 2]])]);
// '[{},{},{},{}]'

// TypedArray
JSON.stringify([new Int8Array([1]), new Int16Array([1]), new Int32Array([1])]);
// '[{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Uint8Array([1]), new Uint8ClampedArray([1]), new Uint16Array([1]), new Uint32Array([1])]);
// '[{"0":1},{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Float32Array([1]), new Float64Array([1])]);
// '[{"0":1},{"0":1}]'

// toJSON()
JSON.stringify({ x: 5, y: 6, toJSON(){ return this.x + this.y} });
// '11'

// Symbols:
JSON.stringify({ x: undefined, y: Object, z: Symbol('') });
// '{}'
JSON.stringify({ [Symbol('foo')]: 'foo' });
// '{}'
JSON.stringify({ [Symbol.for('foo')]: 'foo' }, [Symbol.for('foo')]);
// '{}'
JSON.stringify({ [Symbol.for('foo')]: 'foo' }, function(k, v) {
  if (typeof k === 'symbol') {
    return 'a symbol';
  }
});
// '{}'

// Nicht-enumerable Eigenschaften:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

Der replacer Parameter

Der replacer Parameter kann entweder eine Funktion oder ein Array sein. Als Funktion erh├Ąlt diese zwei Parameter, den Schl├╝ssel und den Wert, die in JSON konvertiert werden. Das Objekt, in dem der Schl├╝ssel gefunden wurde, kann in der replacer Funktion mit this abgefragt werden. Initial wird die replacer Funktion mit einem leeren String als Schl├╝ssel aufgerufen, was bedeutet, dass das Objekt konvertiert wird und dieses dann f├╝r alle Eigenschaften des Objektes oder Arrays die replacer Funktion aufruft. Die Funktion kann den R├╝ckgabewert wie folgt zur├╝ckgeben, damit das Objekt zum JSON-String hinzugef├╝gt wird:

  • Wenn eine Number zur├╝ckgegeben wird, wird der entsprechende String der Zahl als Wert f├╝r die Eigenschaft zum JSON hinzugef├╝gt.
  • Wenn ein String zur├╝ckgegeben wird, wird der String als Wert f├╝r die Eigenschaft zum JSON hinzugef├╝gt.
  • Wenn ein Boolean zur├╝ckgegeben wird, werden "true" oder "false" als Wert f├╝r die Eigenschaft im JSON hinzugef├╝gt.
  • Wenn null zur├╝ckgegeben wird, wird null zum JSON String kinzugef├╝gt.
  • Wenn ein anderes Objekt zur├╝ckgegeben wird, wird dieses Objekt wiederum rekursiv in ein JSON-String konvertiert, was bedeutet, dass f├╝r jede Eigenschaft auch die replacer Funktion wieder aufgerufen wird. Eine Ausnahme ist, wenn das zur├╝ckgegebene Objekt eine Funktion ist, dann wird nichts zum JSON hinzugef├╝gt.
  • Wenn undefined zur├╝ckgegeben wird, wird die Eigenschaft nicht in das JSON hinzugef├╝gt.
Hinweis: Man kann eine replacer Funktion nicht nutzen, um Werte von Arrays zu entfernen. Wenn man undefined oder eine function zur├╝ckgibt, wird null zum JSON hinzugef├╝gt.
Hinweis: Wenn man m├Âchten, dass der Replacer ein initiales Objekt von einem Schl├╝ssel mit einer leeren String-Eigenschaft unterscheidet (da beide den leeren String als Schl├╝ssel und m├Âglicherweise ein Objekt als Wert angeben w├╝rden), muss man den Anzahl der Iterationen verfolgen (wenn er jenseits der ersten Iteration ist, ist es ein echter leerer String-Schl├╝ssel).

Beispiel mit einer Funktion

function replacer(key, value) {
  if (typeof value === "string") {
    return undefined;
  }
  return value;
}

var foo = {foundation: "Mozilla", model: "box", week: 45, transport: "car", month: 7};
var jsonString = JSON.stringify(foo, replacer);
//  {"week":45,"month":7} 

Beispiel mit einem Array

Wenn replacer ein Array ist, geben die Werte des Arrays die Namen der Eigenschaften an, die im JSON-String mit aufgenommen werden sollen.

JSON.stringify(foo, ['week', 'month']);
// '{"week":45,"month":7}', only keep "week" and "month" properties

Der space Parameter

Der space Parameter wird eingesetzt, um die Abst├Ąnde in dem JSON-String zu beeinflussen. Wenn es eine Zahl ist, werden sukzessiv alle Stufen um die angegebene Anzahl von Leerzeichen (bis zu 10) einger├╝ckt. Wenn space ein String ist, werden sukzessiv alle Stufen mit dem angegebenen String einger├╝ckt (oder mit den ersten zehn Zeichen).

JSON.stringify({ a: 2 }, null, ' ');
// '{
//  "a": 2
// }'

Einsatz eines Tab-Zeichens als Standard f├╝r leserliches Aussehen:

JSON.stringify({ uno: 1, dos: 2 }, null, '\t');
// returns the string:
// '{
//     "uno": 1,
//     "dos": 2
// }'

toJSON() Verhalten

Wenn ein Objekt in ein JSON-String umgewandelt werden soll und eine Eigenschaft mit dem Namen toJSON, dessen Wert eine Funktion ist, wird die toJSON() Funktion eingesetzt um ein JSON-String zu erstellen: Anstatt, dass das Objekt normal serialisiert wird, wird die toJSON() Funktion aufgerufen und der R├╝ckgabewert serialisiert. JSON.stringify ruft toJSON mit einem Parameter auf:

  • wenn das Objekt ein Eigenschaftswert ist, dann der Name der Eigenschaft
  • wenn es ein Array ist, dann den Index im Array als String
  • ein leerer String, wenn JSON.stringify direkt auf dem Objekt aufgerufen wurde

Zum Beispiel:

var obj = {
    data: 'data',

    toJSON(key){
        if(key)
            return `Now I am a nested Object under key '${key}'`;

        else
            return this;
    }
};

JSON.stringify(obj);
// Returns '{"data":"data"}'

JSON.stringify({ obj });
// Returns '{"obj":"Now I am a nested object under key 'obj'"}'

JSON.stringify([ obj ])
// Returns '["Now I am a nested object under key '0'"]'

Probleme mit JSON.stringify bei zyklischen Referenzen

Zu beachten ist, dass das JSON Format keine Objektreferenzen unterst├╝tzt (es existiert nur ein IETF Entwurf), so dass ein TypeError erzeugt wird, wenn ein Objekt mit zyklischen Referenzen ├╝bersetzt werden soll.

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

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

Um zyklische Referenzen zu Serialisieren, wird ein Bibliothek mit solchen Funktionen ben├Âtigt (z. B. cycle.js von Douglas Crockford) oder es muss eine eigene L├Âsung implementiert werden, welche zyklische Referenzen bei serialisierbaren Werten findet und ersetzt (oder entfernt).

Probleme mit reinem Einsatz von JSON.stringify f├╝r JavaScript

Man muss anmerken, dass JSON keine komplette strikte Untermenge von JavaScript ist (englisch). Es gibt n├Ąmlich zwei Zeilentrenner (Zeilentrenner und Paragraphentrenner), die in JSON nicht escaped werden m├╝ssen, in JavasScript jedoch schon. Wenn ein JSON nun ausgewertet oder direkt in JSONP eingesetzt werden soll, kann der folgende Quelltext verwendet werden:

function jsFriendlyJSONStringify (s) {
    return JSON.stringify(s).
        replace(/\u2028/g, '\\u2028').
        replace(/\u2029/g, '\\u2029');
}

var s = {
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029)
};
try {
    eval('(' + JSON.stringify(s) + ')');
} catch (e) {
    console.log(e); // "SyntaxError: unterminated string literal"
}

// kein catch ben├Âtigt
eval('(' + jsFriendlyJSONStringify(s) + ')');

// console.log in Firefox unescapes den Unicode wenn
// in die Konsole geloggt wird, weshalb hier alert eingesetzt wird.
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

Beispiel f├╝r Einsatz von JSON.stringify() mit localStorage

In einem Fall, indem man ein Objekt speichern m├Âchte, dass von einem Benutzer erstellt wurde, und dem Benutzer dieses auch nach dem Schlie├čen des Browsers wieder zur Verf├╝gung stellten m├Âchte, ist ein Beispiel f├╝r die Anwendung von JSON.stringify():

// Creating an example of JSON
var 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 });

// Konvertiert zu einem JSON-String mit JSON.stringify().
// Dann wird der String des session-Objektes im localStorage gespeichert.
localStorage.setItem('session', JSON.stringify(session));

// Beispiel wie man den mit JSON.stringify() generierten und
// im localStorage gespeicherten JSON-String in ein Objekt umwandelt.
var restoredSession = JSON.parse(localStorage.getItem('session'));

// Jetzt enth├Ąlt die Variable restoredSession das im localStorage
// abgespeicherte Objekt
console.log(restoredSession);

Spezifikationen

Spezifikation Status Kommentar
ECMAScript 5.1 (ECMA-262)
Die Definition von 'JSON.stringify' in dieser Spezifikation.
Standard Initiale Definition. Implementiert in JavaScript 1.7.
ECMAScript 2015 (6th Edition, ECMA-262)
Die Definition von 'JSON.stringify' in dieser Spezifikation.
Standard
ECMAScript (ECMA-262)
Die Definition von 'JSON.stringify' in dieser Spezifikation.
Lebender Standard

Browserkompatibilit├Ąt

BCD tables only load in the browser

Siehe auch

  • JSON.parse()
  • cycle.js ÔÇô F├╝hrt zwei Funktionen ein, JSON.decycle und JSON.retrocycle, welche es erm├Âglichen zyklische Strukturen zu kodieren und dekodieren und eine erweiterbare und JSON Format kompatible Struktur bietet.