path: root/files/pt-br/web/javascript/reference/global_objects/symbol/index.html

---
title: Símbolo
slug: Web/JavaScript/Reference/Global_Objects/Symbol
translation_of: Web/JavaScript/Reference/Global_Objects/Symbol
---
<div>{{JSRef("Global_Objects", "Symbol")}}</div>

<h2 id="Summary" name="Summary">Sumário</h2>

<p>A função <code>Symbol()</code> retorna um valor do tipo <strong>símbolo (symbol)</strong>, tem propriedades estáticas que expõem vários membros dos objetos nativos, possuem métodos estáticos que expõem o registro de símbolos globais e se parecem com uma classe de objeto nativo, mas estão incompletos como construtor porque não suportam a sintaxe "<code>new Symbol()</code>".</p>

<p>Cada valor símbolo retornado de <code>Symbol()</code> é único. Um símbolo pode ser usado como o identificador para propriedades de objetos; esse é o único propósito do tipo de dado. Algumas explicações sobre propósito e uso podem ser encontradas {{Glossary("Symbol", "no verbete do glossário para Symbol")}}.</p>

<p>O tipo de dado <strong>símbolo</strong> é um {{Glossary("Primitive", "tipo de dado primitivo")}}.</p>

<h2 id="Syntax" name="Syntax">Sintaxe</h2>

<pre class="syntaxbox notranslate"><code>Symbol(<em>[descrição]</em>)</code></pre>

<h3 id="Parameters" name="Parameters">Parâmetros</h3>

<dl>
 <dt><code>descrição</code> {{optional_inline}}</dt>
 <dd>String opcional. Uma descrição de símbolo no qual pode ser usado para debugar, mas não para acessar o próprio símbolo.</dd>
</dl>

<h2 id="Description" name="Description">Descrição</h2>

<p>Para criar um novo símbolo primitivo, simplesmente escreva <code>Symbol()</code> com uma string opcional para sua descrição:</p>

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

<p>O código acima cria três símbolos novos. Note que a função <strong><em>Symbol("foo")</em></strong> não faz a string <strong><em>"foo"</em></strong> ser um símbolo. Ela cria um novo símbolo a cada vez que é chamada:</p>

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

<p>A sintaxe a seguir com o operador {{jsxref("Operators/new", "new")}} vai resultar em um {{jsxref("TypeError")}}:</p>

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

<p>Isso evita que os autores criem um objeto empacotador explícito de <code>Symbol</code> em vez de um novo valor de símbolo. O que pode surpreender, pois, geralmente é possível criar objetos empacotadores explícitos em torno de tipos de dados primitivos (por exemplo, <code>new Boolean</code>, <code>new String</code> e <code>new Number</code>).</p>

<p>Se você realmente quiser criar um objeto empacotador de <code>Symbol</code>, você pode usar a função <code>Object()</code>:</p>

<pre class="brush: js notranslate">var sym = Symbol("foo");
typeof sym;     // "symbol"
var symObj = Object(sym);
typeof symObj;  // "object"
</pre>

<h3 id="Símbolos_compartilhados_no_registro_global_de_símbolo">Símbolos compartilhados no registro global de símbolo</h3>

<p>A sintaxe acima usando a função <code>Symbol()</code> não criará um símbolo global que estará disponível em todo o seu código. Para criar símbolos disponíveis em vários arquivos em um escopo como se fosse global, use os métodos {{jsxref("Symbol.for()")}} e {{jsxref("Symbol.keyFor()")}} para definir e configurar símbolos no registro global de símbolo.</p>

<h3 id="Encontrando_propriedades_de_símbolos_em_objetos">Encontrando propriedades de símbolos em objetos</h3>

<p>O método {{jsxref("Object.getOwnPropertySymbols()")}} retorna um array de símbolos e permite que você encontre propriedades de símbolos em um determinado objeto. Observe que cada objeto é inicializado sem suas próprias propriedades de símbolo, de modo que este array estará vazio, a menos que você estabeleça propriedades de símbolo no objeto.</p>

<h2 id="Properties" name="Properties">Propriedades</h2>

<dl>
 <dt><code>Symbol.length</code></dt>
 <dd>Propriedade de tamanho cujo valor é 1.</dd>
 <dt>{{jsxref("Symbol.prototype")}}</dt>
 <dd>Representa o protótipo do <code>Symbol</code> construtor.</dd>
</dl>

<h3 id="Símbolos_conhecidos">Símbolos conhecidos</h3>

<p>Em adição para seus próprios símbolos, JavaScript possui alguns símbolos built-in que representa os comportamentos internos da linguagem que não foram revelados para os desenvolvedores no ECMAScript 5 e anterior. Esses símbolos podem ser acessados usando as seguintes propriedades:</p>

<dl>
 <dt>Symbol.hasInstance</dt>
 <dd>Especificado como @@hasInstance. Um método que determina se um construtor de um objeto é reconhecido como a instância de um objeto. Usado por {{jsxref("Operators/instanceof", "instanceof")}}.</dd>
 <dt>Symbol.isConcatSpreadable</dt>
 <dd>Especificado como @@isConcatSpreadable. Um valor Booleano indicando se um objeto deve ser adicionado como elemento de uma array. Usado por {{jsxref("Array.prototype.concat()")}}.</dd>
 <dt>Symbol.isRegExp</dt>
 <dd>Especificado como @@isRegExp. Um valor Booleano indicando se um objeto pode ser usado como uma expressão regular.</dd>
 <dt>Symbol.iterator</dt>
 <dd>Especificado como @@iterator. Um método retornando o iterador padrão para um objeto. Usado por <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of"><code>for...of</code></a>.</dd>
 <dt>Symbol.toPrimitive</dt>
 <dd>Especificado como @@toPrimitive. Um método convertendo um objeto para um valor primitivo.</dd>
 <dt>Symbol.toStringTag</dt>
 <dd>Especificado como @@toStringTag. Um valor string usado para descrição padrão de um objeto. Usado por {{jsxref("Object.prototype.toString()")}}</dd>
 <dt>Symbol.unscopables</dt>
 <dd>Especificado como @@unscopables. Uma Array com valores string que são valores propriedade. Esses são excluídos das ligações com o objeto associado.</dd>
</dl>

<h2 id="Methods" name="Methods">Métodos</h2>

<dl>
 <dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt>
 <dd>Procura por símbolos existentes com as chaves dada e retorna as chaves se forem encontradas. Caso contrário um novo símbolo será criado no registro de símbolo global com essa chave.</dd>
 <dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt>
 <dd>Retorna um símbolo compartilhado do registro global de símbolo para o símbolo dado.</dd>
</dl>

<h2 id="Boolean_instances" name="Boolean_instances"><code>Symbol</code> protótipo</h2>

<p>Todos os símbolos herdados de {{jsxref("Symbol.prototype")}}.</p>

<h3 id="Propriedades">Propriedades</h3>

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

<h3 id="Métodos">Métodos</h3>

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

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

<h3 id="Creating_Boolean_objects_with_an_initial_value_of_false" name="Creating_Boolean_objects_with_an_initial_value_of_false">Usando o operador <code>typeof</code> com símbolos</h3>

<p>O operador {{jsxref("Operators/typeof", "typeof")}} pode ajudar a identificar os símbolos.</p>

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

<h3 id="Conversões_de_tipos_de_símbolo">Conversões de tipos de símbolos</h3>

<p>Algumas anotações quando trabalhando com conversão de tipo de símbolos.</p>

<ul>
 <li>Quando estiver tentando converter um símbolo para um número, um {{jsxref("TypeError")}} será retornado.<br>
  (e.g. <code>+sym</code> or <code>sym | 0</code>).</li>
 <li>Quando usando operador de igualdade, <code>Object(sym) == sym</code> retorna <code>true</code>.</li>
 <li><code>Symbol("foo") + "bar" </code>lança um {{jsxref("TypeError")}} (não pode converter um símbolo para string). Isso previne você de silenciosamente criar um novo nome de propriedade string a partir de um símbolo, por exemplo.</li>
 <li>A <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"safer" <code>String(sym)</code> conversion</a> funciona como uma chamada para {{jsxref("Symbol.prototype.toString()")}} com símbolos, mas note que uma <code>new String(sym)</code> será lançada.</li>
</ul>

<h3 id="Símbolos_e_for...in_iteração">Símbolos e <code>for...in</code> iteração</h3>

<p>Símbolos não são visíveis em <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...in"><code>for...in</code></a> iterações. Além de, {{jsxref("Object.getOwnPropertyNames()")}} não retornará propriedades do objeto símbolo, entretanto, você pode fazer uso do {{jsxref("Object.getOwnPropertySymbols()")}} para conseguir esses resultados.</p>

<pre class="brush: js notranslate">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="Símbolos_e_JSON.stringify">Símbolos e <code>JSON.stringify()</code></h3>

<p>Propriedade com chave de símbolo vão ser completamente ignoradas quando usando <code>JSON.stringify()</code>:</p>

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

<p>Para mais detalhes, veja {{jsxref("JSON.stringify()")}}.</p>

<h3 id="Objeto_wrapper_de_símbolo_como_chave_de_propriedade">Objeto wrapper de símbolo como chave de propriedade</h3>

<p>Quando um objeto wrapper de um símbolo é usado como uma chave de propriedade, esse objeto será coerced para o seu símbolo wrapper:</p>

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

<h2 id="Especificações">Especificações</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>Definição inicial.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Compatibilidade com navegadores</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.0")}}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop("36.0")}}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>Symbol.unscopables (@@unscopables)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>
    <div>{{ CompatNo() }}</div>
   </td>
  </tr>
  <tr>
   <td>Other well-known symbols</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</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>{{ CompatNo() }}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{ CompatGeckoMobile("36.0") }}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{ CompatNo() }}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{ CompatGeckoMobile("36.0") }}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>
    <div>Symbol.unscopables (@@unscopables)</div>
   </td>
   <td>{{ CompatNo() }}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>25</td>
   <td>{{ CompatNo() }}</td>
  </tr>
  <tr>
   <td>Other well-known symbols</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
   <td>{{ CompatNo() }}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also" name="See_also">Veja também</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>
</ul>