JSON.stringify() メソッドはある JavaScript の値を JSON 文字列に変換します。置き換え関数を指定して値を置き換えたり、置き換え配列を指定して指定されたプロパティのみを含むようにしたりすることができます。

構文

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

引数

value
JSON 文字列に変換する値。
replacer Optional
文字列化の手順の挙動を変更する関数、または値のオブジェクトを JSON 文字列に含めるプロパティを選択するホワイトリストとして機能する StringNumber オブジェクトの配列。もしこの値が null であるか提供されない場合は、結果の文字列にオブジェクトのすべてのプロパティが含まれます。
space Optional
出力する JSON 文字列に可読性を目的に空白を挿入するために使う String または Number オブジェクト。これが Number のときは空白として使う空白文字の数を示します。この数字は上限が 10 に設定されていて 10 より大きい場合 10 となります。1 より小さい値は空白を使わないことを示します。これが String のときはその文字列(10 文字より長い場合はその最初の 10 文字)が空白として使われます。もしこの引数が提供されない(または null である)場合は、空白は使用されません。

返値

与えられた値を表現する JSON 文字列。

説明

JSON.stringify() は値をそれを表す JSON 表記に変換します。

  • BooleanNumberString オブジェクトは文字列化の際に慣習的な変換セマンティクスに従い、対応する基本的な値に変換されます。
  • 変換の際に undefined、関数、シンボルに出会った場合、それは省略される(オブジェクトで見つかった時)か null に変更されます(配列で見つかった時)。 JSON.stringifyJSON.stringify(function(){})JSON.stringify(undefined) のように「純粋」な値を渡した場合に undefined を返すことがあります。
  • プロパティのキーがシンボルであるプロパティはすべて、replacer 関数を使用する場合でも完全に無視されます。
  • enumerable でないプロパティは無視されます。
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}'
JSON.stringify([new Number(3), new String('false'), new Boolean(false)]);
// '[3,"false",false]'

JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] }); 
// '{"x":[10,null,null,null]}' 
 
// シンボル:
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';
  }
});
// '{}'

// enumerable でないプロパティ:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

replacer 引数

replacer 引数は関数または配列です。関数については、キーと文字列化される値の 2 つの引数を取ります。キーをもつオブジェクトが replacerthis パラメータとして提供されます。最初に文字列化されるオブジェクトを表す空のキーで呼ばれ、それからそれぞれの文字列化されるオブジェクトや配列のプロパティについて呼ばれます。 JSON 文字列に加える値を、次のように返します。

  • Number を返した場合、その数値に対応する文字列が JSON 文字列に追加される時にそのプロパティの値として使用されます。
  • String を返した場合、その文字列が JSON 文字列に追加される時にそのプロパティの値として使用されます。
  • Boolean を返した場合、"true" または "false" が適切に JSON 文字列に追加される時にそのプロパティの値として使用されます。
  • その他のオブジェクトを返した場合、そのオブジェクトは再帰的に JSON 文字列に文字列化されます。その時それぞれのプロパティに対して、そのオブジェクトが関数である場合を除いて replacer 関数を呼びます。関数である場合は JSON 文字列には何も追加されません。
  • undefined を返した場合、そのプロパティは出力する JSON 文字列には含まれません。
注: 配列から値を取り除くために replacer 関数を使うことはできません。 undefined または関数を返した場合は代わりに null が使われます。

関数を使った例

function replacer(key, value) {
  // Filtering out properties
  if (typeof value === 'string') {
    return undefined;
  }
  return value;
}

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

配列を使った例

replacer が配列である場合、その配列の値は結果の JSON 文字列に含めるプロパティの名前を示します。

JSON.stringify(foo, ['week', 'month']);  
// '{"week":45,"month":7}', "week" と "month" プロパティだけが保持される

space 引数

space 引数で最終的な文字列でのスペーシングを調整できます。数値であれば、レベルの階層がそれぞれその数の空白文字(最大10文字)でインデントされます。文字列であれば、レベル階層がそれぞれこの文字列(またはその最初の10文字)でインデントされます。

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

タブ文字を使うと、標準的な表示の整形と同様になります。

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

toJSON() の挙動

文字列化されるオブジェクトに toJSON という名前の値に関数を持ったプロパティがある場合、その toJSON() メソッドで JSON の文字列化の挙動をカスタマイズできます。シリアライズされるオブジェクトの代わりに、その toJSON() メソッドが呼び出されたときの返値がシリアライズされます。 JSON.stringify()toJSON に以下のどれか1つの引数をつけて呼び出します。

  • このオブジェクトがプロパティの値であった場合は、プロパティ名
  • 配列内の値で会った場合は、配列のインデックス番号を文字列で
  • JSON.stringify() がこのオブジェクトに対して直接呼び出された場合は、から文字列

const bonnie = {
  name: 'Bonnie Washington',
  age: 17,
  class: 'Year 5 Wisdom',
  isMonitor: false,
  toJSON: function(key) {
    // 元のオブジェクトを誤って変更しないようにオブジェクトの複製を作る
    const cloneObj = { ...this };

    delete cloneObj.age;
    delete cloneObj.isMonitor;
    cloneObj.year = 5;
    cloneObj.class = 'Wisdom';

    if (key) {
      cloneObj.code = key;
    }

    return cloneObj;
  }
}

JSON.stringify(bonnie);
// '{"name":"Bonnie Washington","class":"Wisdom","year":5}' を返す

const students = {bonnie};
JSON.stringify(students);
// '{"bonnie":{"name":"Bonnie Washington","class":"Wisdom","year":5,"code":"bonnie"}}' を返す

const monitorCandidate = [bonnie];
JSON.stringify(monitorCandidate)
// '[{"name":"Bonnie Washington","class":"Wisdom","year":5,"code":"0"}]' を返す

JavaScript としての使用に際してのそのままの JSON.stringify の問題

JSON は JavaScript の完全に厳密なサブセットではないことに注意してください。2つの行末文字(改行と改段落)は JSON ではエスケープする必要はありませんが、 JavaScript ではエスケープする必要があります。したがって、 JSON が評価式として使われたり、 JSONP の中で直接用いられたりする場合は、次のユーティリティが使えます。

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"
}

// catch する必要はない
eval('(' + jsFriendlyJSONStringify(s) + ')');

// Firefox での console.log はコンソールにログ出力をする場合
//   Unicode エスケープを解除するので、alert を使う
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

localStorageJSON.stringify() を使った例

ユーザーが作成したオブジェクトを格納し、ブラウザーが閉じた後に復元できるようにしたい場合は以下の例が JSON.stringify() を適用した模範例です。

関数は有効な JSON のデータではないため、うまく動作しません。しかし、先に(例えば replacer の中で)関数の toString メソッドによって文字列に変換すれば、表示することができます。また、 Date のような一部のオブジェクトは JSON.parse() の後で文字列になります。

// 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 });

// JSON.stringify() で JSON 文字列に変換してから
// session の名前で localStorage に保存
localStorage.setItem('session', JSON.stringify(session));

// JSON.stringify() で生成されて localStorage に保存された文字列を
// 再び JSON オブジェクトに変換する方法の例
var restoredSession = JSON.parse(localStorage.getItem('session'));

// ここで変数 restoredSession には localStorage に保存されていた
// オブジェクトが入っている
console.log(restoredSession);

仕様策定状況

仕様書 策定状況 コメント
ECMAScript 5.1 (ECMA-262)
JSON.stringify の定義
標準 初回定義。JavaScript 1.7 で実装。
ECMAScript 2015 (6th Edition, ECMA-262)
JSON.stringify の定義
標準  
ECMAScript Latest Draft (ECMA-262)
JSON.stringify の定義
ドラフト  

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOS 版 SafariSamsung InternetNode.js
基本対応Chrome 完全対応 ありEdge 完全対応 ありFirefox 完全対応 3.5IE 完全対応 8Opera 完全対応 10.5Safari 完全対応 4WebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile 完全対応 ありFirefox Android 完全対応 4Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 ありnodejs 完全対応 あり

凡例

完全対応  
完全対応

関連情報

ドキュメントのタグと貢献者

このページの貢献者: FujiHaruka, mfuji09, twe, teoli
最終更新者: FujiHaruka,