Você está lendo a versão em inglês deste conteúdo porque ainda não há uma tradução para este idioma. Ajude-nos a traduzir este artigo!
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])
Parametros
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 simbolo primitivo, simplesmente escreva Symbol()
com uma string opçional para sua descrição:
var sym1 = Symbol(); var sym2 = Symbol("foo"); var sym3 = Symbol("foo");
O codigo acima cria três simbolos novos. Note que a função Symbol("foo") não faz a string "foo" ser um símbolo. Ela cria um novo simbolo 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()
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
- Represents the prototype for the
Symbol
constructor.
Well-known symbols
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:
- Symbol.hasInstance
- Especificado como @@hasInstance. Um método que determina se um construtor de um objeto é reconhecido como a instancia de um objeto. Usado por
instanceof
. - Symbol.isConcatSpreadable
- Specified as @@isConcatSpreadable. A Boolean value indicating if an object should be flattened to its array elements. Used by
Array.prototype.concat()
. - Symbol.isRegExp
- Specified as @@isRegExp. A Boolean value indicating if an object may be used as a regular expression.
- Symbol.iterator
- Specified as @@iterator. A method returning the default iterator for an object. Used by
for...of
. - Symbol.toPrimitive
- Specified as @@toPrimitive. A method converting an object to a primitive value.
- Symbol.toStringTag
- Specified as @@toStringTag. A string value used for the default description of an object. Used by
Object.prototype.toString()
- Symbol.unscopables
- Specified as @@unscopables. An Array of string values that are property values. These are excluded from the with environment bindings of the associated objects.
Métodos
Symbol.for(key)
- 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.
Symbol.keyFor(sym)
- Retrieves a shared symbol key from the global symbol registry for the given symbol.
Symbol
prototype
All Symbols inherit from Symbol.prototype
.
Properties
Symbol.prototype.constructor
- Returns the function that created an instance's prototype. This is the
Symbol
function by default. Symbol.prototype.description
- A read-only string containing the description of the symbol.
Methods
Symbol.prototype.toSource()
- Returns a string containing the source of the
Symbol
object. Overrides theObject.prototype.toSource()
method. Symbol.prototype.toString()
- Returns a string containing the description of the Symbol. Overrides the
Object.prototype.toString()
method. Symbol.prototype.valueOf()
- Returns the primitive value of the
Symbol
object. Overrides theObject.prototype.valueOf()
method. Symbol.prototype[@@toPrimitive]
- Returns the primitive value of the
Symbol
object.
Exemplos
Using the typeof
operator with symbols
The typeof
operator can help you to identify symbols.
typeof Symbol() === 'symbol' typeof Symbol('foo') === 'symbol' typeof Symbol.iterator === 'symbol'
Symbol type conversions
Some things to note when working with type conversion of symbols.
- When trying to convert a symbol to a number, a
TypeError
will be thrown
(e.g.+sym
orsym | 0
). - When using loose equality,
Object(sym) == sym
returnstrue.
Symbol("foo") + "bar"
throws aTypeError
(can't convert symbol to string). This prevents you from silently creating a new string property name from a symbol, for example.- The "safer"
String(sym)
conversion works like a call toSymbol.prototype.toString()
with symbols, but note thatnew String(sym)
will throw.
Symbols and for...in
iteration
Symbols are not visible in for...in
iterations. In addition, Object.getOwnPropertyNames()
will not return symbol object properties, however, you can use Object.getOwnPropertySymbols()
to get these.
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" }
Symbols and JSON.stringify()
Symbol-keyed properties will be completely ignored when using JSON.stringify()
:
JSON.stringify({[Symbol("foo")]: "foo"}); // '{}'
Para mais detalhes, veja JSON.stringify()
.
Symbol wrapper objects as property keys
When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:
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 do navegador
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | 38 | 36.0 (36.0) | Não suportado | 25 | Não suportado |
Symbol.iterator (@@iterator) | 38 | 36.0 (36.0) | Não suportado | 25 | Não suportado |
Symbol.unscopables (@@unscopables) | 38 | Não suportado | Não suportado | 25 |
Não suportado
|
Other well-known symbols | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | Não suportado | 38 | 36.0 (36.0) | Não suportado | 25 | Não suportado |
Symbol.iterator (@@iterator) | Não suportado | 38 | 36.0 (36.0) | Não suportado | 25 | Não suportado |
Symbol.unscopables (@@unscopables)
|
Não suportado | 38 | ? | Não suportado | 25 | Não suportado |
Other well-known symbols | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado |