---
title: Symbol
slug: Web/JavaScript/Referencje/Obiekty/Symbol
translation_of: Web/JavaScript/Reference/Global_Objects/Symbol
---
<div>{{JSRef}}</div>

<p>Funkcja <code>Symbol()</code> zwraca wartość typu <strong>symbol</strong>, posiada statyczne własności wystawiające kilka wartości używanych we wbudowanych obiektach, posiada statyczne metody wystawiające globalny rejestr symboli i przypomina wbudowaną klasę obiektu, jest jednak niekompletna jako konstruktor ponieważ nie wspiera składni "<code>new Symbol()</code>".  </p>

<p>Każdy symbol zwrócony przez <code>Symbol()</code> jest unikalny. Symbol powinien być użyty jako identyfikator własności obiektu, został zaprojektowany jedynie w tym celu. Pełniejsze wyjaśnienie dotyczące jego przeznaczenia i użycia można znaleźć w <a href="/en-US/docs/Glossary/Symbol">poświęconym mu wpisie w glosariuszu</a>.</p>

<p>Typ <strong>symbol</strong> jest {{Glossary("Primitive", "typem prostym")}}.</p>

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



<h2 id="Składnia">Składnia</h2>

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

<h3 id="Parametry">Parametry</h3>

<dl>
 <dt><code>opis</code> {{optional_inline}}</dt>
 <dd>Ciąg znaków, parametr opcjonalny. Opis symbolu, może być użyty do debugowania, ale nie do dostania się do samego symbolu.</dd>
</dl>

<h2 id="Opis">Opis</h2>

<p>Aby stworzyć nowy symbol należy użyć funkcji <code>Symbol()</code>, opcjonalnie przekazując jej opisowy ciąg znaków:</p>

<pre class="brush: js">var sym1 = Symbol();
var sym2 = Symbol('foo');
var sym3 = Symbol('foo');
</pre>

<p>Powyższy kod tworzy trzy nowe symbole. Należy zwrócić uwagę, że <code>Symbol("foo")</code> nie konwertuje ciągu znaków "foo" na symbol, tylko tworzy za każdym razem nowy symbol:</p>

<pre class="brush: js">Symbol('foo') === Symbol('foo'); // false</pre>

<p>Następująca składnia z operatorem {{jsxref("Operators/new", "new")}} spowoduje wyjątek {{jsxref("TypeError")}}:</p>

<pre class="brush: js">var sym = new Symbol(); // TypeError</pre>

<p>Dzieje się tak dlatego żeby powstrzymać programistów przed opakowywaniem wartości symboli w obiekty i może być zaskakujące, gdyż tworzenie opakowanych wartości dla typów prostych jest zazwyczaj możliwe (na przykład <code>new Boolean</code>, <code>new String</code> i <code>new Number</code>).</p>

<p>Jeśli stworzenie opakowanego symbolu jest dokładnie tym czego chce programista, może do tego użyć funkcji <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="Symbole_współdzielone_w_globalnym_rejestrze_symboli">Symbole współdzielone w globalnym rejestrze symboli</h3>

<p>Powyższa składnia używająca funkcji <code>Symbol()</code> nie stworzy globalnego symbolu, który będzie dostępny w całym kodzie. Aby stworzyć symbol dostępny między plikami, a nawet między sferami (z których każda ma swoją globalną przestrzeń) należy użyć metody {{jsxref("Symbol.for()")}}. Z kolei metody {{jsxref("Symbol.keyFor()")}} można użyć aby uzyskać nazwę globalnego klucza dla posiadanego symbolu.</p>

<h3 id="Znajdowanie_własności_indeksowanych_symbolami_na_obiekcie">Znajdowanie własności indeksowanych symbolami na obiekcie</h3>

<p>Metoda {{jsxref("Object.getOwnPropertySymbols()")}} zwraca tablicę symboli i pozwala znaleźć własności indeksowane symbolami na danym obiekcie. Każdy obiekt jest inicjowany bez takich własności, więc metoda ta zwróci pustą tablicę do czasu ustawienia na obiekcie własności pod kluczem typu symbol.</p>

<h2 id="Własności">Własności</h2>

<dl>
 <dt><code>Symbol.length</code></dt>
 <dd>Własność length której wartością jest 0.</dd>
 <dt>{{jsxref("Symbol.prototype")}}</dt>
 <dd>Reprezentuje prototyp konstruktora <code>Symbol</code>.</dd>
</dl>

<h3 id="Znane_symbole">Znane symbole</h3>

<p>Oprócz symboli zdefiniowanych przez programistę, JavaScript posiada wbudowane symbole reprezentujące wewnętrzne mechanizmy języka, które nie były widoczne dla programisty w wersji ECMAScript 5 i wcześniejszych. Dostęp do tych symboli jest możliwy za pomocą następujących własności statycznych:</p>

<h4 id="Symbole_iteracji">Symbole iteracji</h4>

<dl>
 <dt>{{jsxref("Symbol.iterator")}}</dt>
 <dd>Metoda zwracająca domyślny iterator dla obiektu. Używana przez <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of"><code>for...of</code></a>.</dd>
 <dt>{{jsxref("Symbol.asyncIterator")}} {{experimental_inline}}</dt>
 <dd>Metoda zwracająca domyślny asynchroniczny iterator dla obiektu. Używana przez <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for-await-of"><code>for await of</code></a>.</dd>
</dl>

<h4 id="Symbole_wyrażeń_regularnych">Symbole wyrażeń regularnych</h4>

<dl>
 <dt>{{jsxref("Symbol.match")}}</dt>
 <dd>Metoda dopasowująca dla ciągu znaków, używana również dla określenia czy obiekt może zostać użyty jako wyrażenie regularne. Używana przez {{jsxref("String.prototype.match()")}}.</dd>
 <dt>{{jsxref("Symbol.replace")}}</dt>
 <dd>Metoda zastępująca dopasowany ciąg w ciągu znaków. Używana przez {{jsxref("String.prototype.replace()")}}.</dd>
 <dt>{{jsxref("Symbol.search")}}</dt>
 <dd>Metoda zwracająca indeks początku ciągu znaków który został dopasowany do wyrażenia regularnego. Używana przez {{jsxref("String.prototype.search()")}}.</dd>
 <dt>{{jsxref("Symbol.split")}}</dt>
 <dd>Metoda dzieląca łańcuch znaków w miejscu w którym został dopasowany do wyrażenia regularnego. Używana przez {{jsxref("String.prototype.split()")}}.</dd>
</dl>

<h4 id="Pozostałe_symbole">Pozostałe symbole</h4>

<dl>
 <dt>{{jsxref("Symbol.hasInstance")}}</dt>
 <dd>Metoda określająca czy konstruktor rozpoznaje obiekt jako swoją instancję. Używana przez {{jsxref("Operators/instanceof", "instanceof")}}.</dd>
 <dt>{{jsxref("Symbol.isConcatSpreadable")}}</dt>
 <dd>Wartość logiczna określająca czy obiekt powinien zostać spłaszczony do jego elementów tablicy. Używana przez {{jsxref("Array.prototype.concat()")}}.</dd>
 <dt>{{jsxref("Symbol.unscopables")}}</dt>
 <dd>Wartość obiektu którego własne i dziediczone nazwy własności są wykluczone ze środowiska <code><a href="/en-US/docs/Web/JavaScript/Reference/Statements/with">with</a></code> powiązanego obiektu.</dd>
 <dt>{{jsxref("Symbol.species")}}</dt>
 <dd>Funkcja konstruktora używana do tworzenia obiektów wywodzących się z danego.</dd>
 <dt>{{jsxref("Symbol.toPrimitive")}}</dt>
 <dd>Metoda konwertująca obiekt na typ prosty.</dd>
 <dt>{{jsxref("Symbol.toStringTag")}}</dt>
 <dd>Ciąg znaków używany dla domyślnego opisu obiektu. Używany przez {{jsxref("Object.prototype.toString()")}}.</dd>
</dl>

<h2 id="Metody">Metody</h2>

<dl>
 <dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt>
 <dd>Szuka istniejącego symbolu o podanym kluczu i zwraca go, jeśli został znaleziony. W przeciwnym razie w globalnym rejestrze tworzony jest nowy symbol o podanym kluczu i również zwracany.</dd>
 <dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt>
 <dd>Zwraca klucz w globalnym rejestrze zapisany dla danego symbolu.</dd>
</dl>

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

<p>Wszystkie symbole dziecidzą po {{jsxref("Symbol.prototype")}}.</p>

<h3 id="Własności_2">Własności</h3>

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

<h3 id="Metody_2">Metody</h3>

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

<h2 id="Przykłady">Przykłady</h2>

<h3 id="Używanie_operatora_typeof_z_symbolami">Używanie operatora <code>typeof</code> z symbolami</h3>

<p>Operator {{jsxref("Operators/typeof", "typeof")}} może pomóc w identyfikacji symboli.</p>

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

<h3 id="Konwersje_typu_symbol">Konwersje typu symbol</h3>

<ul>
 <li>Podczas próby konwersji symbolu na liczbę zostanie rzucony wyjątek {{jsxref("TypeError")}}.<br>
  (np. <code>+sym</code> lub <code>sym | 0</code>).</li>
 <li>Przy porównaniu z pominięciem typu <code>Object(sym) == sym</code> zwraca <code>true.</code></li>
 <li><code>Symbol("foo") + "bar" </code>wyrzuci {{jsxref("TypeError")}} (nie można skonwertować symbolu na ciąg znaków). Służy to powstrzymaniu programisty na przykład przed stworzeniem nowej nazwy własności z użyciem symbolu.</li>
 <li><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"Bezpieczniejsza" konwersja <code>String(sym)</code></a> działa jak wywołanie {{jsxref("Symbol.prototype.toString()")}} ale należy mieć na uwadze, że <code>new String(sym)</code> rzuci wyjątkiem.</li>
</ul>

<h3 id="Symbole_i_iteracja_for...in">Symbole i iteracja <code>for...in</code></h3>

<p>Symbole nie są iterowalne w pętlach <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...in"><code>for...in</code></a>. Dodatkowo, {{jsxref("Object.getOwnPropertyNames()")}} nie zwróci własności obiektu zapisanych pod kluczem którym jest symbol, do tego celu można użyć {{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); // loguje "c" i "d"
}</pre>

<h3 id="Symbole_i_JSON.stringify()">Symbole i <code>JSON.stringify()</code></h3>

<p>Własności obiektu znajdujące się pod kluczem w postaci symbolu są ignorowane przez <code>JSON.stringify()</code>:</p>

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

<p>Żeby dowiedzieć się więcej zobacz {{jsxref("JSON.stringify()")}}.</p>

<h3 id="Symbole_opakowane_w_obiekty_jako_klucze_własności">Symbole opakowane w obiekty jako klucze własności</h3>

<p>Gdy symbol opakowany w obiekt jest użyty jako klucz własności, obiekt opakowujący zostanie skonwertowany do symbolu który opakowuje:</p>

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

<h2 id="Specyfikacje">Specyfikacje</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specyfikacja</th>
   <th scope="col">Status</th>
   <th scope="col">Komentarz</th>
  </tr>
  <tr>
   <td>{{SpecName('ES2015', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ES2015')}}</td>
   <td>Wstępna definicja</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Kompatybilność_przeglądarek">Kompatybilność przeglądarek</h2>



<p>{{Compat("javascript.builtins.Symbol")}}</p>

<h2 id="Zobacz_również">Zobacz również</h2>

<ul>
 <li><a href="/en-US/docs/Glossary/Symbol">Glosariusz: typ Symbol</a></li>
 <li>{{jsxref("Operators/typeof", "typeof")}}</li>
 <li><a href="/en-US/docs/Web/JavaScript/Data_structures">Typy i struktury danych</a></li>
 <li><a href="https://hacks.mozilla.org/2015/06/es6-in-depth-symbols/">"ES6 In Depth: Symbols" na hacks.mozilla.org</a></li>
</ul>