---
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("javascript.builtins.Symbol")}}</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>