Símbolo

Sumário

A função Symbol() retorna um valor do tipo símbolo (symbol), 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 "new Symbol()".

Cada valor símbolo retornado de Symbol() é ú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 no verbete do glossário para Symbol.

O tipo de dado símbolo é um tipo de dado primitivo.

Sintaxe

Symbol([descrição])

Parâmetros

descrição Optional

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.

Descrição

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

var sym1 = Symbol();
var sym2 = Symbol("foo");
var sym3 = Symbol("foo");

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

Symbol("foo") === Symbol("foo"); // false

A sintaxe a seguir com o operador new vai resultar em um TypeError:

var sym = new Symbol(); // TypeError

Isso evita que os autores criem um objeto empacotador explícito de Symbol 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, new Boolean, new String e new Number).

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

var sym = Symbol("foo");
typeof sym;     // "symbol"
var symObj = Object(sym);
typeof symObj;  // "object"

Símbolos compartilhados no registro global de símbolo

A sintaxe acima usando a função Symbol() 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 Symbol.for() (en-US) e Symbol.keyFor() (en-US) para definir e configurar símbolos no registro global de símbolo.

Encontrando propriedades de símbolos em objetos

O método 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.

Propriedades

Symbol.length

Propriedade de tamanho cujo valor é 1.

Symbol.prototype (en-US)

Representa o protótipo do Symbol construtor.

Símbolos conhecidos

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:

Symbol.hasInstance

Especificado como @@hasInstance. Um método que determina se um construtor de um objeto é reconhecido como a instância de um objeto. Usado por instanceof.

Symbol.isConcatSpreadable

Especificado como @@isConcatSpreadable. Um valor Booleano indicando se um objeto deve ser adicionado como elemento de uma array. Usado por Array.prototype.concat().

Symbol.isRegExp

Especificado como @@isRegExp. Um valor Booleano indicando se um objeto pode ser usado como uma expressão regular.

Symbol.iterator

Especificado como @@iterator. Um método retornando o iterador padrão para um objeto. Usado por for...of.

Symbol.toPrimitive

Especificado como @@toPrimitive. Um método convertendo um objeto para um valor primitivo.

Symbol.toStringTag

Especificado como @@toStringTag. Um valor string usado para descrição padrão de um objeto. Usado por Object.prototype.toString()

Symbol.unscopables

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.

Métodos

Symbol.for(key) (en-US)

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.

Symbol.keyFor(sym) (en-US)

Retorna um símbolo compartilhado do registro global de símbolo para o símbolo dado.

Symbol protótipo

Todos os símbolos herdados de Symbol.prototype (en-US).

Propriedades

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

Métodos

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

Exemplos

Usando o operador typeof com símbolos

O operador typeof pode ajudar a identificar os símbolos.

typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'

Conversões de tipos de símbolos

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

  • Quando estiver tentando converter um símbolo para um número, um TypeError será retornado. (e.g. +sym or sym | 0).
  • Quando usando operador de igualdade, Object(sym) == sym retorna true.
  • Symbol("foo") + "bar" lança um 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.
  • A "safer" String(sym) conversion funciona como uma chamada para Symbol.prototype.toString() (en-US) com símbolos, mas note que uma new String(sym) será lançada.

Símbolos e for...in iteração

Símbolos não são visíveis em for...in iterações. Além de, Object.getOwnPropertyNames() não retornará propriedades do objeto símbolo, entretanto, você pode fazer uso do Object.getOwnPropertySymbols() para conseguir esses resultados.

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"
}

Símbolos e JSON.stringify()

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

JSON.stringify({[Symbol("foo")]: "foo"});
// '{}'

Para mais detalhes, veja JSON.stringify().

Objeto wrapper de símbolo como chave de propriedade

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

var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1

Especificações

Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Symbol' in that specification.
Padrão Definição inicial.

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também