Símbolo - JavaScript | MDN

Toggle sidebar

Theme

OS default
Light
Dark

Português (do Brasil)

Remember language Learn more

Símbolo

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since setembro de 2015.

* Some parts of this feature may have varying levels of support.

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:

js
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():

js
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() e Symbol.keyFor() 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

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)

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)

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

js
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() 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.

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

Símbolos e JSON.stringify()

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

js
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:

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

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 27 de abr. de 2025 by MDN contributors.

View this page on GitHub • Report a problem with this content

Objetos Globais
Symbol
Construtor
1. Symbol()
Métodos estáticos
1. for()
2. keyFor()
Propriedades estáticas
Métodos de instância
Propriedades de instância
1. Symbol.prototype.description
Herança
Object/Function
Métodos estáticos
Propriedades estáticas
Métodos de instância
Propriedades de instância
1. Object.prototype.__proto__
2. Object.prototype.constructor

Símbolo

Sumário

In this article

Sintaxe

Parâmetros

Descrição

Símbolos compartilhados no registro global de símbolo

Encontrando propriedades de símbolos em objetos

Propriedades

Símbolos conhecidos

Métodos

Symbol protótipo

Propriedades

Métodos

Exemplos

Usando o operador typeof com símbolos

Conversões de tipos de símbolos

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

Símbolos e JSON.stringify()

Objeto wrapper de símbolo como chave de propriedade

Especificações

Compatibilidade com navegadores

Veja também

Help improve MDN