JSON.stringify()

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

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 dieses, 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.

Beschreibung

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

• Eigenschaften von nicht-Array Objekten werden nicht in einer bestimmten Reihenfolge angegeben. In dem Ergebnisobjekt wird keine Reihenfolge garantiert.
• 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.
• Nicht-aufzählbare (non-enumerable) Eigenschaften werden ignoriert.

JSON.stringify({});                  // '{}'
JSON.stringify(true);                // 'true'
JSON.stringify('foo');               // '"foo"'
JSON.stringify([1, 'false', false]); // '[1,"false",false]'
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]}'

// 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 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 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.

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 die alle Stufen um die angegebene Anzahl von Leerzeichen (bit 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. Zum Beispiel:

var obj = {
  foo: 'foo',
  toJSON: function() {
    return 'bar';
  }
};
JSON.stringify(obj);        // '"bar"'
JSON.stringify({ x: obj }); // '{"x":"bar"}'

Probleme mit reinem Einsatz von JSON.stringify für JavaScript

Bemerkenswert ist, dass JSON keine komplette strikte Untermenge von JavaScript ist (englisch). Mit zwei Zeilentrennern (Zeilentrenner und Paragraphentrenner) müssen nicht in JSON escaped werden, jedoch müssen diese in JavaScript escaped werden. Wenn ein JSON nun ausgewertet werden soll oder direkt in JSONP eingesetzt werden soll, kann der folgende Quelltext helfen:

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

Browserkompatibilität

Siehe auch

• JSON.parse()