path: root/files/uk/web/javascript/reference/global_objects/symbol/index.html

---
title: Symbol
slug: Web/JavaScript/Reference/Global_Objects/Symbol
tags:
  - ECMAScript 2015
  - JavaScript
  - NeedsTranslation
  - Symbol
  - TopicStub
translation_of: Web/JavaScript/Reference/Global_Objects/Symbol
---
<div>{{JSRef}}</div>

<p><strong>Символ</strong> є {{Glossary("Primitive", "простим типом даних")}}. Функція  <code>Symbol()</code> вертає значення типу <strong>символ</strong>, має статичні властивості, що відкривають декілька членів вбудованих об'єктів, має статичні методи, що відкривають глобальний реєстр символів, та нагадує вбудований клас об'єкта, але не є повноцінним конструктором, оскільки не підтримує синтаксис "<code>new Symbol()</code>".</p>

<p>Кожне символьне значення, що його вертає <code>Symbol()</code>, є унікальним. Символьне значення може використовуватись в якості ідентифікатора властивостей об'єкта; це єдина мета цього типу даних. Більше пояснень щодо мети та використання можна знайти у <a href="/uk/docs/Glossary/Символ">статті словника щодо символів</a>.</p>

<p>{{EmbedInteractiveExample("pages/js/symbol-constructor.html")}}</p>

<div class="hidden">
<p>The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> and send us a pull request.</p>
</div>

<h2 id="Синтаксис">Синтаксис</h2>

<pre class="syntaxbox">Symbol(<em>[description]</em>)</pre>

<h3 id="Параметри">Параметри</h3>

<dl>
 <dt><code>description</code> {{optional_inline}}</dt>
 <dd>Необов'язковий, рядок. Опис символу, який можна використовувати для відлагодження, але не для доступу для самого символу.</dd>
</dl>

<h2 id="Опис">Опис</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> не приводить рядок "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>Symbol</code>, ви можете скористатись функцією <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">Properties</h2>

<dl>
 <dt><code>Symbol.length</code></dt>
 <dd>Length property whose value is 0.</dd>
 <dt>{{jsxref("Symbol.prototype")}}</dt>
 <dd>Represents the prototype for the <code>Symbol</code> constructor.</dd>
</dl>

<h3 id="Well-known_symbols">Well-known symbols</h3>

<p>In addition to your own symbols, JavaScript has some built-in symbols which represent internal language behaviors which were not exposed to developers in ECMAScript 5 and before. These symbols can be accessed using the following properties:</p>

<h4 id="Iteration_symbols">Iteration symbols</h4>

<dl>
 <dt>{{jsxref("Symbol.iterator")}}</dt>
 <dd>A method returning the default iterator for an object. Used by <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of"><code>for...of</code></a>.</dd>
</dl>

<h4 id="Regular_expression_symbols">Regular expression symbols</h4>

<dl>
 <dt>{{jsxref("Symbol.match")}}</dt>
 <dd>A method that matches against a string, also used to determine if an object may be used as a regular expression. Used by {{jsxref("String.prototype.match()")}}.</dd>
 <dt>{{jsxref("Symbol.replace")}}</dt>
 <dd>A method that replaces matched substrings of a string. Used by {{jsxref("String.prototype.replace()")}}.</dd>
 <dt>{{jsxref("Symbol.search")}}</dt>
 <dd>A method that returns the index within a string that matches the regular expression. Used by {{jsxref("String.prototype.search()")}}.</dd>
 <dt>{{jsxref("Symbol.split")}}</dt>
 <dd>A method that splits a string at the indices that match a regular expression. Used by {{jsxref("String.prototype.split()")}}.</dd>
</dl>

<h4 id="Other_symbols">Other symbols</h4>

<dl>
 <dt>{{jsxref("Symbol.hasInstance")}}</dt>
 <dd>A method determining if a constructor object recognizes an object as its instance. Used by {{jsxref("Operators/instanceof", "instanceof")}}.</dd>
 <dt>{{jsxref("Symbol.isConcatSpreadable")}}</dt>
 <dd>A Boolean value indicating if an object should be flattened to its array elements. Used by {{jsxref("Array.prototype.concat()")}}.</dd>
 <dt>{{jsxref("Symbol.unscopables")}}</dt>
 <dd>An object value of whose own and inherited property names are excluded from the <code><a href="/en-US/docs/Web/JavaScript/Reference/Statements/with">with</a></code> environment bindings of the associated object.</dd>
 <dt>{{jsxref("Symbol.species")}}</dt>
 <dd>A constructor function that is used to create derived objects.</dd>
 <dt>{{jsxref("Symbol.toPrimitive")}}</dt>
 <dd>A method converting an object to a primitive value.</dd>
 <dt>{{jsxref("Symbol.toStringTag")}}</dt>
 <dd>A string value used for the default description of an object. Used by {{jsxref("Object.prototype.toString()")}}.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt>
 <dd>Searches for existing symbols with the given key and returns it if found. Otherwise a new symbol gets created in the global symbol registry with this key.</dd>
 <dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt>
 <dd>Retrieves a shared symbol key from the global symbol registry for the given symbol.</dd>
</dl>

<h2 id="Symbol_prototype"><code>Symbol</code> prototype</h2>

<p>All Symbols inherit from {{jsxref("Symbol.prototype")}}.</p>

<h3 id="Properties_2">Properties</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}</p>

<h3 id="Methods_2">Methods</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}</p>

<h2 id="Examples">Examples</h2>

<h3 id="Using_the_typeof_operator_with_symbols">Using the <code>typeof</code> operator with symbols</h3>

<p>The {{jsxref("Operators/typeof", "typeof")}} operator can help you to identify symbols.</p>

<pre class="brush: js">typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'
</pre>

<h3 id="Symbol_type_conversions">Symbol type conversions</h3>

<p>Some things to note when working with type conversion of symbols.</p>

<ul>
 <li>When trying to convert a symbol to a number, a {{jsxref("TypeError")}} will be thrown<br>
  (e.g. <code>+sym</code> or <code>sym | 0</code>).</li>
 <li>When using loose equality, <code>Object(sym) == sym</code> returns <code>true.</code></li>
 <li><code>Symbol("foo") + "bar" </code>throws a {{jsxref("TypeError")}} (can't convert symbol to string). This prevents you from silently creating a new string property name from a symbol, for example.</li>
 <li>The <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"safer" <code>String(sym)</code> conversion</a> works like a call to {{jsxref("Symbol.prototype.toString()")}} with symbols, but note that <code>new String(sym)</code> will throw.</li>
</ul>

<h3 id="Symbols_and_for...in_iteration">Symbols and <code>for...in</code> iteration</h3>

<p>Symbols are not enumerable in <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...in"><code>for...in</code></a> iterations. In addition, {{jsxref("Object.getOwnPropertyNames()")}} will not return symbol object properties, however, you can use {{jsxref("Object.getOwnPropertySymbols()")}} to get these.</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); // logs "c" and "d"
}</pre>

<h3 id="Symbols_and_JSON.stringify">Symbols and <code>JSON.stringify()</code></h3>

<p>Symbol-keyed properties will be completely ignored when using <code>JSON.stringify()</code>:</p>

<pre class="brush: js">JSON.stringify({[Symbol('foo')]: 'foo'});
// '{}'</pre>

<p>For more details, see {{jsxref("JSON.stringify()")}}.</p>

<h3 id="Symbol_wrapper_objects_as_property_keys">Symbol wrapper objects as property keys</h3>

<p>When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:</p>

<pre class="brush: js">var sym = Symbol('foo');
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1
</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('ES2015', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ES2015')}}</td>
   <td>Initial definition</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.unscopables (@@unscopables)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.match (@@match)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(40)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.species (@@species)</td>
   <td>{{CompatChrome(51)}}</td>
   <td>{{CompatGeckoDesktop(41)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toPrimitive (@@toPrimitive)</td>
   <td>{{CompatChrome(48)}}</td>
   <td>{{CompatGeckoDesktop(44)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.replace (@@replace)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.search (@@search)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.split (@@split)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.isConcatSpreadable (@@isconcatspreadable)</td>
   <td>{{CompatChrome(48)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.hasInstance (@@hasInstance)</td>
   <td>{{CompatChrome(51)}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toStringTag (@@toStringTag)</td>
   <td>{{CompatChrome(49)}}</td>
   <td>{{CompatGeckoDesktop(51)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.unscopables (@@unscopables)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.match (@@match)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(40)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.species (@@species)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(41)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toPrimitive (@@toPrimitive)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(44)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.replace (@@replace)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.search (@@search)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.split (@@split)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.isConcatSpreadable (@@isconcatspreadable)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.hasInstance (@@hasInstance)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toStringTag (@@toStringTag)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(51)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Glossary/Symbol">Glossary: Symbol data type</a></li>
 <li>{{jsxref("Operators/typeof", "typeof")}}</li>
 <li><a href="/en-US/docs/Web/JavaScript/Data_structures">Data types and data structures</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>