diff options
Diffstat (limited to 'files/uk/web/javascript/reference/global_objects/json')
3 files changed, 612 insertions, 0 deletions
diff --git a/files/uk/web/javascript/reference/global_objects/json/index.html b/files/uk/web/javascript/reference/global_objects/json/index.html new file mode 100644 index 0000000000..af5818da2a --- /dev/null +++ b/files/uk/web/javascript/reference/global_objects/json/index.html @@ -0,0 +1,158 @@ +--- +title: JSON +slug: Web/JavaScript/Reference/Global_Objects/JSON +tags: + - JSON + - JavaScript + - Довідка + - Об'єкт +translation_of: Web/JavaScript/Reference/Global_Objects/JSON +--- +<div>{{JSRef}}</div> + +<p>Об'єкт <strong><code>JSON</code></strong> містить методи для розбору <a class="external" href="http://json.org/">JavaScript Object Notation</a> ({{glossary("JSON")}}) і конвертації значень у JSON. Його можна або просто викликати, або конструювати; і окрім своїх двох методів він не має у собі іншої корисної функціональності.</p> + +<h2 id="Опис">Опис</h2> + +<h3 id="Об'єктна_нотація_JavaScript">Об'єктна нотація JavaScript</h3> + +<p>JSON - це синтаксис для серіалізації об'єктів, масивів, чисел, строк, булевих значень, та {{jsxref("null")}}. Він заснований на синтаксисі JavaScript, проте дещо відрізняється від нього: деякий JavaScript не є JSON, і деякий JSON не є JavaScript. Докладніше у <a href="http://timelessrepo.com/json-isnt-a-javascript-subset">JSON: The JavaScript subset that isn't</a>.</p> + +<table> + <caption>Відмінності JavaScript і JSON</caption> + <thead> + <tr> + <th scope="col">Тип у JavaScript</th> + <th scope="col">Відмінність у JSON</th> + </tr> + </thead> + <tbody> + <tr> + <td>Об'єкти та масиви</td> + <td>Назви полів повинні являти собою строки у подвійних лапках; прикінцеві коми заборонені.</td> + </tr> + <tr> + <td>Числа</td> + <td>Ведучі нулі також заборонені (При виконанні JSON.stringify нулі просто проігноруються, проте JSON.parse викине SyntaxError); після десяткової крапки повинна слідувати хоча б одна цифра.</td> + </tr> + <tr> + <td>Строки</td> + <td> + <p>Лише обмежений набір символів можна екранувати; деякі керівні символи заборонені; такі символи юнікоду, як розділювач рядків (<a href="http://unicode-table.com/en/2028/">U+2028</a>) та розділювач абзаців (<a href="http://unicode-table.com/en/2029/">U+2029</a>) дозволені; строки повинні виділятись подвійними лапками. Зверніть увагу на наступні приклади, де {{jsxref("JSON.parse()")}} нормально працює, проте при обчисленні виразу як JavaScript-коду буде отримана помилка {{jsxref("SyntaxError")}}:</p> + + <pre class="brush: js"> +var code = '"\u2028\u2029"'; +JSON.parse(code); // працює +eval(code); // помилка +</pre> + </td> + </tr> + </tbody> +</table> + +<p>Повний синтаксис JSON виглядає так:</p> + +<pre><var>JSON</var> = <strong>null</strong> + або <strong>true</strong> або <strong>false</strong> + або <var>JSONNumber</var> + або <var>JSONString</var> + або <var>JSONObject</var> + або <var>JSONArray</var> + +<var>JSONNumber</var> = <strong>-</strong> <var>PositiveNumber</var> + <em>чи</em> <var>PositiveNumber</var> +<var>PositiveNumber</var> = DecimalNumber + або <var>DecimalNumber</var> <strong>.</strong> <var>Digits</var> + <em>або</em> <var>DecimalNumber</var> <strong>.</strong> <var>Digits</var> <var>ExponentPart</var> + або <var>DecimalNumber</var> <var>ExponentPart</var> +<var>DecimalNumber</var> = <strong>0</strong> + або <var>OneToNine</var> <var>Digits</var> +<var>ExponentPart</var> = <strong>e</strong> <var>Exponent</var> + чи <strong>E</strong> <var>Exponent</var> +<var>Exponent</var> = <var>Digits</var> + <em>або</em> <strong>+</strong> <var>Digits</var> + або <strong>-</strong> <var>Digits</var> +<var>Digits</var> = <var>Digit</var> + чи <var>Digits</var> <var>Digit</var> +<var>Digit</var> = від <strong>0</strong> до <strong>9</strong> +<var>OneToNine</var> = <strong>від 1</strong> до <strong>9</strong> + +<var>JSONString</var> = <strong>""</strong> + <em>чи</em> <strong>"</strong> <var>StringCharacters</var> <strong>"</strong> +<var>StringCharacters</var> = <var>StringCharacter</var> + чи <var>StringCharacters</var> <var>StringCharacter</var> +<var>StringCharacter</var> = будь-який символ + за виключенням <strong>"</strong> або <strong>\</strong> або від U+0000 до U+001F + або <var>EscapeSequence</var> +<var>EscapeSequence</var> = <strong>\"</strong> або <strong>\/</strong> або <strong>\\</strong> або <strong>\b</strong> або <strong>\f</strong> або <strong>\n</strong> або <strong>\r</strong> або <strong>\t</strong> + або <strong>\u</strong> <var>HexDigit</var> <var>HexDigit</var> <var>HexDigit</var> <var>HexDigit</var> +<var>HexDigit</var> = від <strong>0</strong> до <strong>9</strong> + або від <strong>A</strong> до <strong>F</strong> + або від <strong>a</strong> до <strong>f</strong> + +<var>JSONObject</var> = <strong>{</strong> <strong>}</strong> + чи <strong>{</strong> <var>Members</var> <strong>}</strong> +<var>Members</var> = <var>JSONString</var> <strong>:</strong> <var>JSON</var> + чи <var>Members</var> <strong>,</strong> <var>JSONString</var> <strong>:</strong> <var>JSON</var> + +<var>JSONArray</var> = <strong>[</strong> <strong>]</strong> + <em>чи</em> <strong>[</strong> <var>ArrayElements</var> <strong>]</strong> +<var>ArrayElements</var> = <var>JSON</var> + <em>чи</em> <var>ArrayElements</var> <strong>,</strong> <var>JSON</var> +</pre> + +<p>Беззмістовні пробільні символи можуть бути будь-де за винятком <code><var>JSONNumber</var></code> (числа не повинні містити пробіли) або <code><var>JSONString</var></code> (де це сприймається за частину строки, або призведе до помилки). Символ табуляції (<a href="http://unicode-table.com/en/0009/">U+0009</a>), повернення каретки (<a href="http://unicode-table.com/en/000D/">U+000D</a>), початку рядка (<a href="http://unicode-table.com/en/000A/">U+000A</a>) та пробіл (<a href="http://unicode-table.com/en/0020/">U+0020</a>) - це всі дійсні пробільні символи.</p> + +<h2 id="Методи">Методи</h2> + +<dl> + <dt>{{jsxref("JSON.parse()")}}</dt> + <dd>Розбирає строку як JSON, як опція — перетворює результат і його властивості, та повертає його.</dd> + <dt>{{jsxref("JSON.stringify()")}}</dt> + <dd>Повертає строку JSON відповідно до поданого значення. Як опція — може включити до результату лише певні поля чи замінити значення полів згідно з побажаннями користувача.</dd> +</dl> + +<h2 id="Специфікації">Специфікації</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Специфікація</th> + <th scope="col">Статус</th> + <th scope="col">Примітка</th> + </tr> + <tr> + <td>{{SpecName('ES5.1', '#sec-15.12', 'JSON')}}</td> + <td>{{Spec2('ES5.1')}}</td> + <td>Первинне визначення.</td> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-json-object', 'JSON')}}</td> + <td>{{Spec2('ES6')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-json-object', 'JSON')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Підтримка_у_браузерах">Підтримка у браузерах</h2> + +<div> +<div> +<div> +<div class="hidden">Таблиця сумісності на цій сторінці сформована автоматично із структурованих даних. Якщо ви маєте бажання зробити свій внесок до цих даних - будь-ласка, ось репозиторій <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</div> + +<p>{{Compat("javascript.builtins.JSON")}}</p> +</div> +</div> +</div> + +<h2 id="Дивіться_також">Дивіться також</h2> + +<ul> + <li>{{jsxref("Date.prototype.toJSON()")}}</li> +</ul> diff --git a/files/uk/web/javascript/reference/global_objects/json/parse/index.html b/files/uk/web/javascript/reference/global_objects/json/parse/index.html new file mode 100644 index 0000000000..685832a864 --- /dev/null +++ b/files/uk/web/javascript/reference/global_objects/json/parse/index.html @@ -0,0 +1,133 @@ +--- +title: JSON.parse() +slug: Web/JavaScript/Reference/Global_Objects/JSON/parse +tags: + - ECMAScript5 + - JSON + - JavaScript + - Method + - Довідка +translation_of: Web/JavaScript/Reference/Global_Objects/JSON/parse +--- +<div>{{JSRef}}</div> + +<div><span class="seoSummary">Метод <code><strong>JSON.parse()</strong></code> розбирає рядок із JSON, створюючи відповідне до його вмісту значення чи об'єкт. Якщо вказати функцію <code>reviver</code> — другий необов'язковий параметр — її буде використано для перетворення створеного об'єкта та його властивостей перед поверненням.</span> + +<div> </div> + +<div>{{EmbedInteractiveExample("pages/js/json-parse.html")}}</div> + +<p class="hidden">Першокод цього прикладу збережено у репозиторії GitHub. Якщо ви хочете долучитися до створення чи поліпшення таких прикладів, пропонуйте нам свої зміни до репозиторію <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a>.</p> +</div> + +<h2 id="Синтаксис">Синтаксис</h2> + +<pre class="syntaxbox">JSON.parse(<var>text</var>[, <var>reviver</var>])</pre> + +<h3 id="Параметри">Параметри</h3> + +<dl> + <dt><code>text</code></dt> + <dd>Рядок, що його має бути розібрано, як JSON. Докладні відомості про синтаксис JSON наведено в статті про об'єкт {{jsxref("JSON")}}.</dd> + <dt><code>reviver</code> {{optional_inline}}</dt> + <dd>Якщо вказано функцію, її буде використано для перетворення отриманих значень перед поверненням.</dd> +</dl> + +<h3 id="Вертає">Вертає</h3> + +<p>{{jsxref("Object", "Об'єкт")}}, що відповідає переданому JSON-рядку.</p> + +<h3 id="Винятки">Винятки</h3> + +<p>Викидає виняток {{jsxref("Global_Objects/SyntaxError", "SyntaxError")}}, якщо вміст переданого рядка не є належним JSON.</p> + +<h2 id="Приклади">Приклади</h2> + +<h3 id="Використання_JSON.parse()">Використання <code>JSON.parse()</code></h3> + +<pre class="brush: js">JSON.parse('{}'); // {} +JSON.parse('{"x": {"value": 1}}'); // {x: {value: 1}} +JSON.parse('true'); // true +JSON.parse('"щось навіщось"'); // "щось навіщось" +JSON.parse('[1, 5, "false"]'); // [1, 5, "false"] +JSON.parse('null'); // null +</pre> + +<h3 id="Використання_параметра_reviver">Використання параметра <code>reviver</code></h3> + +<p>Якщо <code>reviver</code> вказано, то його буде використано для <em>перетворення</em> кожного значення, отриманого шляхом розбору JSON-рядка. Кожне значення (об'єкт та всі його властивості) окремо піддається перетворенню за допомогою <code>reviver</code> в порядку зсередини назовні (від властивостей найглибше вкладених об'єктів). Задля перетворення чергової властивості до функції <code>reviver</code> передається два аргументи: ім'я властивості (рядок) та її значення. Посилання <code>this</code> вказує на об'єкт, що містить зазначену властивість.</p> + +<p>Якщо функція <code>reviver</code> повертає {{jsxref("undefined")}} (або взагалі не вертає значення), властивість буде видалено з об'єкта. Інакше повернуте значення буде встановлено замість попереднього. Отже, якщо ви маєте на меті перетворити лише деякі значення, для решти функція <code>reviver</code> має вертати значення другого аргументу без змін.</p> + +<pre class="brush: js">JSON.parse('{"p": 5, "x": "5"}', function (key, value) { + return typeof value === 'number' + ? value * 2 // Повернути подвоєне значення, якщо це число. + : value // Решту значень повернути без змін. +}); + +// { p: 10, x: "5" } + +JSON.parse('{"1": 1, "2": 2, "3": {"4": 4, "5": {"6": 6}}}', function (key, value) { + // Вивести ім'я чергової властивості (для останньої це порожній рядок — ""). + console.log(key); + + // Повернути значення властивості без змін. + return value; +}); + +// 1 +// 2 +// 4 +// 6 +// 5 +// 3 +// "" +</pre> + +<h3 id="Прикінцеві_коми_вважаються_за_помилку">Прикінцеві коми вважаються за помилку</h3> + +<pre class="example-bad brush: js example-bad">// Обидва виклики викидають SyntaxError. +JSON.parse('[1, 2, 3, 4, ]'); +JSON.parse('{"foo" : 1, }'); +</pre> + +<h2 id="Специфікації">Специфікації</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Специфікація</th> + <th scope="col">Статус</th> + <th scope="col">Коментар</th> + </tr> + <tr> + <td>{{SpecName('ES5.1', '#sec-15.12.2', 'JSON.parse')}}</td> + <td>{{Spec2('ES5.1')}}</td> + <td>Початкова виознака. Запроваджено у JavaScript 1.7.</td> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-json.parse', 'JSON.parse')}}</td> + <td>{{Spec2('ES6')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-json.parse', 'JSON.parse')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Підтримка_веб-переглядачами">Підтримка веб-переглядачами</h2> + +<div> +<div class="hidden">Таблиця сумісності на цій сторінці створена зі структурованих даних. Якщо ви хочете долучитися до розробки цих даних, пропонуйте нам свої pull request до репозиторію <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</div> + +<p>{{Compat("javascript.builtins.JSON.parse")}}</p> +</div> + +<h2 id="Див._також">Див. також</h2> + +<ul> + <li>{{jsxref("JSON.stringify()")}}</li> +</ul> diff --git a/files/uk/web/javascript/reference/global_objects/json/stringify/index.html b/files/uk/web/javascript/reference/global_objects/json/stringify/index.html new file mode 100644 index 0000000000..ca0fdc87fc --- /dev/null +++ b/files/uk/web/javascript/reference/global_objects/json/stringify/index.html @@ -0,0 +1,321 @@ +--- +title: JSON.stringify() +slug: Web/JavaScript/Reference/Global_Objects/JSON/stringify +tags: + - JSON + - JavaScript + - stringify + - Довідка + - метод +translation_of: Web/JavaScript/Reference/Global_Objects/JSON/stringify +--- +<div>{{JSRef}}</div> + +<p>Метод <strong><code>JSON.stringify()</code></strong> подає об'єкт чи {{glossary("Primitive", "просту величину")}} як JSON-рядок, певним чином перетворюючи або оминаючи ті чи ті властивості, якщо вказано необов'язковий другий аргумент — функцію або масив <code>replacer</code>.</p> + +<div>{{EmbedInteractiveExample("pages/js/json-stringify.html")}}</div> + +<p class="hidden">Джерело цих інтерактивних прикладів зберігається у репозиторії на GitHub. Якщо ви маєте бажання зробити свій внесок у проект інтерактивних прикладів - будь ласка, зклонуйте репозиторій <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> та пришліть нам pull request.</p> + +<h2 id="Синтаксис">Синтаксис</h2> + +<pre class="syntaxbox"><code>JSON.stringify(<var>value</var>[, <var>replacer</var>[, <var>space</var>]])</code></pre> + +<h3 id="Параметри">Параметри</h3> + +<dl> + <dt><code>value</code></dt> + <dd>Значення, яке слід перетворити на рядок JSON.</dd> + <dt><code>replacer</code> {{optional_inline}}</dt> + <dd>Функція, що змінює значення перед їхнім перетворенням на JSON, або масив {{jsxref("Global_Objects/String", "рядків")}} та {{jsxref("Global_Objects/Number", "чисел")}}, що окреслюють множину властивостей, які буде включено у створений JSON-рядок. Якщо цей аргумент відсутній чи вказано <code>null</code>, до створеного JSON-рядка потраплять всі наявні властивості об'єкта без змін.</dd> + <dt><code>space</code> {{optional_inline}}</dt> + <dd>Значення типу {{jsxref("Global_Objects/String", "String")}} або {{jsxref("Число", "Number")}} що використовується для додавання відступів у JSON задля покращення легкочитності. Якщо вказано число — воно означає кількість пропусків в одному відступі. Якщо передати число більше за 10, буде використано 10. Значення менші за 1 вказують на те що відступи не використовуватимуться. Якщо вказано рядок, то його (або перші 10 символів, якщо він задовгий) буде використано як відступ. Якщо ж параметр не вказано (або <code>null</code>), відступи не додаватимуться.</dd> +</dl> + +<h3 id="Вертає">Вертає</h3> + +<p>Рядок JSON, створений із вказаного значення.</p> + +<h3 id="Винятки">Винятки</h3> + +<p>Викидає виняток {{jsxref("TypeError")}} ("cyclic object value") у випадку, якщо знайдено циклічне посилання.</p> + +<h2 id="Опис">Опис</h2> + +<p>Функція <code>JSON.stringify()</code> перетворює значення на рядок, що містить JSON-запис того значення:</p> + +<ul> + <li>Якщо значення має свій метод <a href="https://developer.mozilla.org/uk/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify$edit#toJSON()_behavior">toJSON()</a>, саме він буде відповідати за дані, що будуть серіалізовані.</li> + <li>Об'єкти {{jsxref("Global_Objects/Boolean", "Boolean")}}, {{jsxref("Число", "Number")}} та {{jsxref("Global_Objects/String", "String")}} в типовий спосіб перетворюються на відповідні {{glossary("Primitive", "прості величини")}};</li> + <li>{{glossary("Function", "Функцію")}}, {{jsxref("undefined")}} або значення типу {{jsxref("Symbol")}} під час перетворення буде або вилучено (якщо знайдено в об'єкті), або обернено на {{jsxref("null")}} (якщо знайдено в масиві). Метод <code>JSON.stringify</code> також може вертати <code>undefined</code>, якщо йому передано «щирі» величини, як-от <code>JSON.stringify(function(){})</code> чи <code>JSON.stringify(undefined)</code>;</li> + <li>Всі властивості, що мають за ключ величину типу {{jsxref("Symbol")}}, буде знехтувано, навіть якщо задіяно функцію <code>replacer</code>;</li> + <li>Екземпляри {{jsxref("Date")}} реалізовують функцію <code>toJSON()</code> шляхом повертання рядку (такого ж, як і <code>date.toISOString()</code>), тому вони будуть вважатись рядками.</li> + <li>Такі числа, як {{jsxref("Infinity")}} та {{jsxref("NaN")}}, так як і об'єкт {{jsxref("null")}} будуть вважатися за <code>null</code>.</li> + <li>Для всіх інших екземплярів {{jsxref("Object")}}, включно з {{jsxref("Map")}}, {{jsxref("Set")}}, {{jsxref("WeakMap")}} та {{jsxref("WeakSet")}} будуть серіалізовані лише їх перелічувані поля.</li> +</ul> + +<pre class="brush: js">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]}' + +// Стандартні структури даних +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' + +// Значення типу Symbol: +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'; + } +}); +// '{}' + +// Неперелічувані властивості: +JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) ); +// '{"y":"y"}' + +</pre> + +<h3 id="Параметер_replacer">Параметер <code>replacer</code></h3> + +<p>Параметр <code>replacer</code> може бути функцією або масивом. Якщо то функція, вона прийматиме два параметри: ключ та значення, яке са́ме перетворюється. Об'єкт, якому належить перетворювана властивість, доступний всередині <code>replacer</code> через <code>this</code>. Спершу функцію буде викликано з порожнім рядком замість ключа й тим об'єктом, який має бути перетворено, а відтак для кожної властивості того об'єкта буде здійснено окремий виклик <code>replacer</code>. Кожен виклик має вертати значення, що належить додати до рядка JSON:</p> + +<ul> + <li>Якщо повернути {{jsxref("Число", "Number")}}, до JSON буде додано текстовий запис числа як значення властивості;</li> + <li>Якщо повернути {{jsxref("String")}}, до JSON буде додано рядок як значення властивості;</li> + <li>Якщо повернути {{jsxref("Boolean")}}, до JSON буде додано «true» або «false» як значення властивості;</li> + <li>Якщо повернути <code>null</code>, <code>null</code> і буде додано до JSON-рядку.</li> + <li>Якщо повернути інший об'єкт або масив, його буде рекурсивно перетворено на JSON в той самий спосіб (викликаючи <code>replacer</code> для кожної його властивості), а тоді додано до JSON як значення властивості (якщо повернутий об'єкт є функцією, до JSON нічого додано не буде);</li> + <li>Якщо повернути {{jsxref("undefined")}}, властивість не потрапить до JSON.</li> +</ul> + +<div class="note"><strong>Заувага:</strong> Вилучати елементи масиву за допомогою <code>replacer</code> неможливо — якщо повернути <code>undefined</code>, значення елемента лише обернеться на <code>null</code>.</div> + +<div class="note"><strong>Note:</strong> If you wish the replacer to distinguish an initial object from a key with an empty string property (since both would give the empty string as key and potentially an object as value), you will have to keep track of the iteration count (if it is beyond the first iteration, it is a genuine empty string key).</div> + +<h4 id="Приклад_із_функцією">Приклад із функцією</h4> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">replacer</span><span class="punctuation token">(</span>key<span class="punctuation token">,</span> value<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token">// Фільтрація властивостей</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span><span class="keyword token">typeof</span> value <span class="operator token">===</span> <span class="string token">'string'</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">return</span> undefined<span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="keyword token">return</span> value<span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">var</span> foo <span class="operator token">=</span> <span class="punctuation token">{</span>foundation<span class="punctuation token">:</span> <span class="string token">'Mozilla'</span><span class="punctuation token">,</span> model<span class="punctuation token">:</span> <span class="string token">'box'</span><span class="punctuation token">,</span> week<span class="punctuation token">:</span> <span class="number token">45</span><span class="punctuation token">,</span> transport<span class="punctuation token">:</span> <span class="string token">'car'</span><span class="punctuation token">,</span> month<span class="punctuation token">:</span> <span class="number token">7</span><span class="punctuation token">}</span><span class="punctuation token">;</span> +JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>foo<span class="punctuation token">,</span> replacer<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="comment token">// '{"week":45,"month":7}'</span></code></pre> + +<h4 id="Приклад_із_масивом">Приклад із масивом</h4> + +<p>Якщо <code>replacer</code> являється масивом, його значення позначають імена властивостей вхідного об'єкту, що будуть включені в результат.</p> + +<p> </p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>foo<span class="punctuation token">,</span> <span class="punctuation token">[</span><span class="string token">'week'</span><span class="punctuation token">,</span> <span class="string token">'month'</span><span class="punctuation token">]</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="comment token">// '{"week":45,"month":7}', будуть збережені лише властивості "week" та "month"</span></code></pre> + +<h3 id="Параметер_space">Параметер <code>space</code></h3> + +<p>Аргумент <code>space</code> може застосовуватись для управління відступами в результуючому рядку. Якщо в якості аргументу дано число, кожен із наступних рівнів серіалізації матиме відступ у вигляді відповідної поданому числу кількості пробілів (але не більше 10). Якщо ж в якості аргументу дано рядок, його і буде використано для виконання відступу (або ж 10 перших символів, якщо сам рядок довший).</p> + +<pre class="brush: js">JSON.stringify({ a: 1, b: {c: 2} }, null, 3); +// Вертає рядок: +// '{ +// "a": 1, +// "b": { +// "c": 2 +// } +// }' +</pre> + +<p>А тут замість пропусків буде вжито символ табуляції:</p> + +<pre class="brush: js">JSON.stringify({ a: 1, b: {c: 2} }, null, '\t'); +// Вертає рядок: +// '{ +// "a": 1, +// "b": { +// "c": 2 +// } +// }' +</pre> + +<h3 id="Особливий_метод_toJSON()">Особливий метод <code>toJSON()</code></h3> + +<p>Й хоча методи перетворюваних об'єктів загалом нехтуються, метод з ім'ям <code>toJSON</code> має особливе призначення. Якщо перетворюваний об'єкт має метод <code>toJSON()</code>, його буде викликано, а повернене значення вжито (перетворено на JSON) замість самого об'єкту. <code>JSON.stringify()</code> викликає метод <code>toJSON</code> з одним аргументом:</p> + +<p> </p> + +<ul> + <li>якщо цей об'єкт являється значенням властивості, то ім'я властивості;</li> + <li>якщо це масив, то рядок із індексом масиву;</li> + <li>порожній рядок, якщо <code>JSON.stringify()</code> було викликано прямо на цьому об'єкті</li> +</ul> + +<p>Наприклад:</p> + +<p> </p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> obj <span class="operator token">=</span> <span class="punctuation token">{</span> + data<span class="punctuation token">:</span> <span class="string token">'data'</span><span class="punctuation token">,</span> + + <span class="function token">toJSON</span><span class="punctuation token">(</span>key<span class="punctuation token">)</span><span class="punctuation token">{</span> + <span class="keyword token">if</span><span class="punctuation token">(</span>key<span class="punctuation token">)</span> + <span class="keyword token">return</span> `Тепер я вкладений об'єкт під ключем <span class="string token">'${key}'</span>`<span class="punctuation token">;</span> + + <span class="keyword token">else</span> + <span class="keyword token">return</span> <span class="keyword token">this</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span> + +JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>obj<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="comment token">// '{"data":"data"}'</span> + +JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span><span class="punctuation token">{</span> obj <span class="punctuation token">}</span><span class="punctuation token">)</span> +<span class="comment token">// '{"obj":"Тепер я вкладений об'єкт під ключем 'obj'"}'</span> + +JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span><span class="punctuation token">[</span> obj <span class="punctuation token">]</span><span class="punctuation token">)</span> +<span class="comment token">// '["Тепер я вкладений об'єкт під ключем '0'"]'</span></code></pre> + +<h3 id="Проблема_із_JSON.stringify()_при_серіалізації_циклічних_посилань">Проблема із <code>JSON.stringify()</code> при серіалізації циклічних посилань</h3> + +<p>Зауважте, що, оскільки <a href="https://www.json.org/">JSON format</a> не підтримує об'єктні посилання (хоча є <a href="http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03">чорновик IETF</a>), при спробі кодування об'єкту із циклічними посиланнями буде отримано {{jsxref("TypeError")}}.</p> + +<pre class="brush: js example-bad line-numbers language-js"><code class="language-js"><span class="keyword token">const</span> circularReference <span class="operator token">=</span> <span class="punctuation token">{</span><span class="punctuation token">}</span><span class="punctuation token">;</span> +circularReference<span class="punctuation token">.</span>myself <span class="operator token">=</span> circularReference<span class="punctuation token">;</span> + +<span class="comment token">// Серіалізація циклічного посилання викине "TypeError: cyclic object value"</span> +JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>circularReference<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>Для виконання серіалізації циклічних посилань ви можете використати бібліотеку, що їх підтримує (зокрема <a href="https://github.com/douglascrockford/JSON-js/blob/master/cycle.js">cycle.js</a> від Douglas Crockford), або ж реалізувати рішення самостійно, для чого знадобиться пошук і заміна (або видалення) циклічних посилань на підходящі для серіалізації значення.</p> + +<h3 class="highlight-spanned" id="Тлумачення_отриманого_JSON_як_коду_JavaScript"><span class="highlight-span">Тлумачення отриманого JSON як коду JavaScript</span></h3> + +<p>Завважте, що <a class="external external-icon" href="http://timelessrepo.com/json-isnt-a-javascript-subset" rel="noopener">JSON не є точнісінькою підмножиною JavaScript</a>. Два розділювачі (рядка та параграфу) не треба екранувати у JSON, але потрібно у JavaScript. Тож якщо ви маєте намір застосувати функцію <a class="new" href="https://developer.mozilla.org/uk/docs/Web/JavaScript/Reference/Global_Objects/eval" rel="nofollow" title="The documentation about this has not yet been written; please consider contributing!"><code>eval()</code></a> або скористатися <a class="external external-icon" href="https://uk.wikipedia.org/wiki/JSONP" rel="noopener" title="JSONP">JSONP</a>, доведеться здійснити невеличкі перетворення:</p> + +<p> </p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> jsFriendlyJSONStringify <span class="punctuation token">(</span>s<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">return</span> JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>s<span class="punctuation token">)</span><span class="punctuation token">.</span> + <span class="function token">replace</span><span class="punctuation token">(</span><span class="regex token">/\u2028/g</span><span class="punctuation token">,</span> <span class="string token">'\\u2028'</span><span class="punctuation token">)</span><span class="punctuation token">.</span> + <span class="function token">replace</span><span class="punctuation token">(</span><span class="regex token">/\u2029/g</span><span class="punctuation token">,</span> <span class="string token">'\\u2029'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">var</span> s <span class="operator token">=</span> <span class="punctuation token">{</span> + a<span class="punctuation token">:</span> String<span class="punctuation token">.</span><span class="function token">fromCharCode</span><span class="punctuation token">(</span><span class="number token">0x2028</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + b<span class="punctuation token">:</span> String<span class="punctuation token">.</span><span class="function token">fromCharCode</span><span class="punctuation token">(</span><span class="number token">0x2029</span><span class="punctuation token">)</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span> +<span class="keyword token">try</span> <span class="punctuation token">{</span> + <span class="function token">eval</span><span class="punctuation token">(</span><span class="string token">'('</span> <span class="operator token">+</span> JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>s<span class="punctuation token">)</span> <span class="operator token">+</span> <span class="string token">')'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> <span class="keyword token">catch</span> <span class="punctuation token">(</span><span class="class-name token">e</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span><span class="punctuation token">;</span> <span class="comment token">// "SyntaxError: unterminated string literal"</span> +<span class="punctuation token">}</span> + +<span class="comment token">// Якщо ловити виключення не має потреби</span> +<span class="function token">eval</span><span class="punctuation token">(</span><span class="string token">'('</span> <span class="operator token">+</span> <span class="function token">jsFriendlyJSONStringify</span><span class="punctuation token">(</span>s<span class="punctuation token">)</span> <span class="operator token">+</span> <span class="string token">')'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="comment token">// console.log у Firefox знімає екранування Юнікоду, якщо</span> +<span class="comment token">// виводиться в консоль, тому застосуймо alert</span> +<span class="function token">alert</span><span class="punctuation token">(</span><span class="function token">jsFriendlyJSONStringify</span><span class="punctuation token">(</span>s<span class="punctuation token">)</span><span class="punctuation token">)</span><span class="punctuation token">;</span> <span class="comment token">// {"a":"\u2028","b":"\u2029"}</span></code></pre> + +<h3 id="Приклад_застосування_JSON.stringify()_із_localStorage">Приклад застосування <code>JSON.stringify()</code> із <code>localStorage</code></h3> + +<p>У випадку, якщо ви хочете зберегти об'єкт, створений вашим користувачем і дозволити відновити його навіть після закриття браузера, ось наступний приклад із моделлю застосування <code>JSON.stringify()</code>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// Створення зразка JSON</span> +<span class="keyword token">var</span> session <span class="operator token">=</span> <span class="punctuation token">{</span> + <span class="string token">'screens'</span><span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + <span class="string token">'state'</span><span class="punctuation token">:</span> <span class="keyword token">true</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenA'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">450</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">250</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenB'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">650</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">350</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenC'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">750</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">120</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenD'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">250</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">60</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenE'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">390</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">120</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +session<span class="punctuation token">.</span>screens<span class="punctuation token">.</span><span class="function token">push</span><span class="punctuation token">(</span><span class="punctuation token">{</span> <span class="string token">'name'</span><span class="punctuation token">:</span> <span class="string token">'screenF'</span><span class="punctuation token">,</span> <span class="string token">'width'</span><span class="punctuation token">:</span> <span class="number token">1240</span><span class="punctuation token">,</span> <span class="string token">'height'</span><span class="punctuation token">:</span> <span class="number token">650</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="comment token">// Конвертація рядка JSON через JSON.stringify()</span> +<span class="comment token">// далі збереження у localStorage із іменем "session</span>" +localStorage<span class="punctuation token">.</span><span class="function token">setItem</span><span class="punctuation token">(</span><span class="string token">'session'</span><span class="punctuation token">,</span> JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span>session<span class="punctuation token">)</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="comment token">// Приклад, як перетворити рядок, отриманий за допомогою </span> +<span class="comment token">// JSON.stringify() і збережений у localStorage назад у JSON-об'єкт</span> +<span class="keyword token">var</span> restoredSession <span class="operator token">=</span> JSON<span class="punctuation token">.</span><span class="function token">parse</span><span class="punctuation token">(</span>localStorage<span class="punctuation token">.</span><span class="function token">getItem</span><span class="punctuation token">(</span><span class="string token">'session'</span><span class="punctuation token">)</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="comment token">// Тепер змінна restoredSession містить об'єкт, що був раніше збережений</span> +<span class="comment token">// у localStorage</span> +console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>restoredSession<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<h2 id="Специфікації">Специфікації</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Специфікація</th> + <th scope="col">Статус</th> + <th scope="col">Коментар</th> + </tr> + <tr> + <td>{{SpecName('ES5.1', '#sec-15.12.3', 'JSON.stringify')}}</td> + <td>{{Spec2('ES5.1')}}</td> + <td>Первинне визначення. Запроваджено у JavaScript 1.7.</td> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-json.stringify', 'JSON.stringify')}}</td> + <td>{{Spec2('ES6')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-json.stringify', 'JSON.stringify')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Підтримка_веб-переглядачами">Підтримка веб-переглядачами</h2> + +<div class="hidden">Таблиця сумісності на цій сторінці створена зі структурованих даних. Якщо ви хочете долучитися до розробки цих даних, пропонуйте нам свої pull request до репозиторію <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</div> + +<div>{{Compat("javascript.builtins.JSON.stringify")}}</div> + +<h2 id="Див._також">Див. також</h2> + +<ul> + <li>{{jsxref("JSON.parse()")}}</li> + <li><a href="https://github.com/douglascrockford/JSON-js/blob/master/cycle.js">cycle.js</a> – Вводить дві функції: <code>JSON.decycle</code> та <code>JSON.retrocycle</code>. Вони дають можливість кодувати і декодувати циклічні структури і ділянки у розширений і зворотньо сумісний формат JSON.</li> +</ul> |