--- title: Symbol slug: Web/JavaScript/Reference/Global_Objects/Symbol tags: - API - ECMAScript6 - JavaScript - Symbol - Символы translation_of: Web/JavaScript/Reference/Global_Objects/Symbol --- <div>{{JSRef}}</div> <h2 id="Summary">Сводка</h2> <p><strong style="line-height: 1.5;">Символ (анг. Symbol)</strong><span style="line-height: 1.5;"> — это уникальный и неизменяемый тип данных, который может быть использован как идентификатор для свойств объектов. </span><em>Символьный объект (анг. symbol object) </em>— это объект-обёртка (англ. wrapper) для <span style="line-height: 1.5;">{{Glossary("Primitive", "примитивного")}} символьного типа.</span></p> <h2 id="Syntax">Синтаксис</h2> <pre class="syntaxbox"><code>Symbol(<em>[описание]</em>)</code></pre> <h3 id="Parameters">Параметры</h3> <dl> <dt><code>описание</code> {{optional_inline}}</dt> <dd>Необязательный, строка. Описание символа, которое может быть использовано во время отладки, но не для доступа к самому символу.</dd> </dl> <h2 id="Description">Описание</h2> <p>Чтобы создать новый символьный примитив, достаточно написать <code>Symbol()</code>, указав по желанию строку в качестве описания этого символа:</p> <pre class="brush: js">var sym1 = Symbol(); var sym2 = Symbol("foo"); var sym3 = Symbol("foo"); </pre> <p>Код выше создаёт три новых символа. Заметьте, что <code>Symbol("foo")</code> не выполняет приведение (англ. coercion) строки "foo" к символу. Это выражение создаёт каждый раз новый символ:</p> <pre class="brush: js">Symbol("foo") === Symbol("foo"); // false</pre> <p>Код ниже с оператором {{jsxref("Operators/new", "new")}} бросит исключение {{jsxref("TypeError")}}:</p> <pre class="brush: js">var sym = new Symbol(); // TypeError</pre> <p>Это удерживает разработчиков от создания явного объекта-обёртки <code>Symbol </code>вместо нового символьного значения. Создание явных объектов-обёрток для примитивных типов доступно (например, <code>new Boolean</code>, <code>new String</code>, <code>new Number</code>).</p> <p>Если вам действительно необходимо обернуть символ в объект, вы можете использовать функцию <code>Object()</code>:</p> <pre class="brush: js">var sym = Symbol("foo"); typeof sym; // "symbol" var symObj = Object(sym); typeof symObj; // "object" </pre> <h3 id="Разделяемые_символы_в_глобальном_символьном_реестре">Разделяемые символы в глобальном символьном реестре</h3> <p>Приведённый выше синтаксис, использующий функцию <code>Symbol(),</code> не создаст глобальный символ, который был бы доступен в любом месте вашего кода. Для создания символов, доступных во всех файлах и в окружении (глобальной области), используйте методы {{jsxref("Symbol.for()")}} и {{jsxref("Symbol.keyFor()")}}, чтобы задать или получить символ из глобального символьного реестра.</p> <h3 id="Поиск_символьных_свойств_у_объектов">Поиск символьных свойств у объектов</h3> <p>Метод {{jsxref("Object.getOwnPropertySymbols()")}} возвращает массив символов и позволяет получить символьные свойства конкретного объекта. Следует заметить, что при инициализации объекты не получают символьных свойств, так что этот массив будет пуст, пока вы не зададите ему какое-либо символьное свойство.</p> <h2 id="Properties">Свойства</h2> <dl> <dt><code>Symbol.length</code></dt> <dd>Содержит длину, всегда равную 0 (нулю).</dd> <dt>{{jsxref("Symbol.prototype")}}</dt> <dd>Содержит прототип конструктора <code>Symbol</code>.</dd> </dl> <h3 id="Известные_символы">Известные символы</h3> <p>В добавок к вашим собственным символам, JavaScript имеет несколько встроенных символов, представляющих внутренние механизмы языка, которые не были доступны разработчикам в версиях ECMAScript 5 и более ранних. Эти символы доступны посредством следующих свойств:</p> <dl> <dt> <h4 id="Итерационные_символы">Итерационные символы</h4> </dt> <dt>{{jsxref("Symbol.iterator")}}</dt> <dd>Метод, возвращающий итератор по умолчанию для объекта. Используется конструкцией {{jsxref("Statements/for...of","for...of")}}.</dd> <dt> <h4 id="Символы_регулярных_выражений">Символы регулярных выражений</h4> </dt> <dt>{{jsxref("Symbol.match")}}</dt> <dd>Метод для сопоставления объекта со строкой, также используемый для определения возможности объекта выступать в качестве регулярного выражения. Используется функцией {{jsxref("String.prototype.match()")}}.</dd> <dt>{{jsxref("Symbol.replace")}}</dt> <dd>Метод, заменяющий совпавшие подстроки в строке. Используется функцией {{jsxref("String.prototype.replace()")}}.</dd> <dt>{{jsxref("Symbol.search")}}</dt> <dd>Метод, возвращающий индекс вхождения подстроки, соответствующей регулярному выражению. Используется функцией {{jsxref("String.prototype.search()")}}.</dd> <dt>{{jsxref("Symbol.split")}}</dt> <dd>Метод, разбивающий строку на части в местах, соответствующих регулярному выражению. Используется функцией {{jsxref("String.prototype.split()")}}. </dd> <dt> <h4 id="Другие_символы">Другие символы</h4> </dt> <dt>{{jsxref("Symbol.hasInstance")}}</dt> <dd>Метод, определяющий, распознает ли конструктор некоторый объект как свой экземпляр. Используется оператором {{jsxref("Operators/instanceof", "instanceof")}}.</dd> <dt>{{jsxref("Symbol.isConcatSpreadable")}}</dt> <dd>Булево значение, показывающее, должен ли объект быть сведён к плоскому представлению (англ. flatten) в виде массива его элементов функцией {{jsxref("Array.prototype.concat()")}}.</dd> <dt>{{jsxref("Symbol.unscopables")}}</dt> <dd>Массив строковых имён свойств. Позволяет скрыть свойства от инструкции with (прежде всего для обратной совместимости).</dd> <dt>{{jsxref("Symbol.species")}}</dt> <dd>Метод, определяющий конструктор для порождённых объектов.</dd> <dt>{{jsxref("Symbol.toPrimitive")}}</dt> <dd>Метод, преобразующий объект в примитив (примитивное значение).</dd> <dt>{{jsxref("Symbol.toStringTag")}}</dt> <dd>Строковое значение, используемое в качестве описания объекта по умолчанию. Используется функцией {{jsxref("Object.prototype.toString()")}}</dd> </dl> <h2 id="Methods">Методы</h2> <dl> <dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt> <dd>Ищет существующие символы по заданному ключу и возвращает его, если он найден. В противном случае создаётся новый символ для данного ключа в глобальном реестре символов.</dd> <dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt> <dd>Получает по разделяемому символу его ключ из глобального реестра символов.</dd> </dl> <h2 id="Boolean_instances"><code><span style="font-family: open sans,sans-serif; font-size: 2.14285714285714rem;">Прототип </span>Symbol</code></h2> <p>Все символы наследуют от {{jsxref("Symbol.prototype")}}.</p> <h3 id="Свойства">Свойства</h3> <p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}</p> <h3 id="Методы">Методы</h3> <p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}</p> <h2 id="Examples">Примеры</h2> <h3 id="Creating_Boolean_objects_with_an_initial_value_of_false">Использование оператора <code>typeof</code> с символами</h3> <p>Оператор {{jsxref("Operators/typeof", "typeof")}} позволяет идентифицировать символ.</p> <pre class="brush: js">typeof Symbol() === 'symbol' typeof Symbol('foo') === 'symbol' typeof Symbol.iterator === 'symbol' </pre> <h3 id="Преобразование_типов_с_символами">Преобразование типов с символами</h3> <p>Следующее необходимо помнить при преобразовании типа символов.</p> <ul> <li>При попытке конвертировать символ в число, будет брошено исключение {{jsxref("TypeError")}} (напр., <code>+sym</code> или <code>sym | 0</code>).</li> <li>Результатом нестрогого сравнения, <code>Object(sym) == sym</code>, будет <code>true.</code></li> <li><code>Symbol("foo") + "bar" </code>бросает исключение {{jsxref("TypeError")}} (невозможно преобразовать символ в строку). Это удерживает разработчика от, к примеру, случайного создания строгого поля у объекта из символа.</li> <li>Более <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"безопасный" вызов <code>String(sym)</code></a> работает с символами как вызов {{jsxref("Symbol.prototype.toString()")}}. Заметьте, что в то же время <code>new String(sym)</code> бросит исключение.</li> </ul> <h3 id="Символы_и_конструкция_for...in">Символы и конструкция <code>for...in</code></h3> <p>Символы не перечисляются при итерации {{jsxref("Statements/for...in","for...in")}}. В дополнение к этому, {{jsxref("Object.getOwnPropertyNames()")}} не вернёт символьные свойства объекта. Тем не менее, их можно получить с помощью {{jsxref("Object.getOwnPropertySymbols()")}}.</p> <pre class="brush: js">var obj = {}; obj[Symbol("a")] = "a"; obj[Symbol.for("b")] = "b"; obj["c"] = "c"; obj.d = "d"; for (var i in obj) { console.log(i); // выведет "c" и "d" }</pre> <h3 id="Символы_и_JSON.stringify">Символы и <code>JSON.stringify()</code></h3> <p><span style="font-family: courier new,andale mono,monospace; line-height: 1.5;">JSON.stringify()</span> игнорирует свойства с ключами <code>Symbol</code>:</p> <pre class="brush: js">JSON.stringify({[Symbol("foo")]: "foo"}); // '{}'</pre> <p>Подробности см. {{jsxref("JSON.stringify()")}}.</p> <h3 id="Объекты-обёртки_для_Symbol_в_качестве_имён_свойств">Объекты-обёртки для Symbol в качестве имён свойств</h3> <p>Когда объект-обёртка символа используется в качестве имени свойства, этот объект сводится к символу, который он оборачивает:</p> <pre class="brush: js">var sym = Symbol("foo"); var obj = {[sym]: 1}; obj[sym]; // 1 obj[Object(sym)]; // снова 1 </pre> <h2 id="Спецификации">Спецификации</h2> {{Specifications}} <h2 id="Поддержка_браузерами">Поддержка браузерами</h2> <p>{{Compat}}</p> <h2 id="See_also">Смотрите также</h2> <ul> <li><a href="/ru/docs/Glossary/Symbol">Глоссарий: Символьный тип данных</a></li> <li>{{jsxref("Operators/typeof", "typeof")}}</li> <li><a href="/ru/docs/Web/JavaScript/Data_structures">Типы и структуры данных JavaScript</a></li> <li><a href="https://hacks.mozilla.org/2015/06/es6-in-depth-symbols/">"ES6 In Depth: Symbols" on hacks.mozilla.org</a></li> </ul>