Символ є простим типом даних. Функція Symbol()
вертає значення типу символ, має статичні властивості, що відкривають декілька членів вбудованих об'єктів, має статичні методи, що відкривають глобальний реєстр символів, та нагадує вбудований клас об'єкта, але не є повноцінним конструктором, оскільки не підтримує синтаксис "new Symbol()
".
Кожне символьне значення, що його вертає Symbol()
, є унікальним. Символьне значення може використовуватись в якості ідентифікатора властивостей об'єкта; це єдина мета цього типу даних. Більше пояснень щодо мети та використання можна знайти у статті словника щодо символів.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Синтаксис
Symbol([description])
Параметри
description
Optional- Необов'язковий, рядок. Опис символу, який можна використовувати для відлагодження, але не для доступу для самого символу.
Опис
Для створення примітивного символа ви пишете Symbol()
з необов'язковим рядком в ролі його опису:
var sym1 = Symbol();
var sym2 = Symbol('foo');
var sym3 = Symbol('foo');
Наведений код створює три нові символи. Зауважте, що Symbol("foo")
не приводить рядок "foo" до символу. Він кожен раз створює новий символ:
Symbol('foo') === Symbol('foo'); // false
Наступний синтаксис з оператором new
викине помилку TypeError
:
var sym = new Symbol(); // TypeError
Це запобігає створенню явного об'єкта-обгортки Symbol
замість нового символьного значення та може дивувати, оскільки створення явного об'єкта-обгортки для примітивних типів даних загалом можливе (для прикладу, new Boolean
, new String
та new Number
).
Якщо вам дуже потрібно створити об'єкт обгортку Symbol
, ви можете скористатись функцією Object()
:
var sym = Symbol('foo');
typeof sym; // "symbol"
var symObj = Object(sym);
typeof symObj; // "object"
Спільні символи у глобальному реєстрі символів
Наведений синтаксис використання функції Symbol()
не створить глобальний символ, доступний з усієї вашої кодової бази. Щоб створити символи, доступні в усіх файлах і навіть у різних сферах (кожна з яких має свою глобальну область видимості), використовуйте методи Symbol.for()
та Symbol.keyFor()
, щоб записувати та читати символи у глобальному реєстрі символів.
Пошук символьних властивостей об'єктів
Метод Object.getOwnPropertySymbols()
повертає масив символів та дозволяє знайти символьні властивості наданого об'єкта. Зауважте, що жоден об'єкт не ініціалізується з особистими символьними властивостями, отже, цей масив буде порожнім, якщо тільки ви не задали символьні властивості об'єкта.
Properties
Symbol.length
- Length property whose value is 0.
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:
Iteration symbols
Symbol.iterator
- A method returning the default iterator for an object. Used by
for...of
.
Regular expression symbols
Symbol.match
- A method that matches against a string, also used to determine if an object may be used as a regular expression. Used by
String.prototype.match()
. Symbol.replace
- A method that replaces matched substrings of a string. Used by
String.prototype.replace()
. Symbol.search
- A method that returns the index within a string that matches the regular expression. Used by
String.prototype.search()
. Symbol.split
- A method that splits a string at the indices that match a regular expression. Used by
String.prototype.split()
.
Other symbols
Symbol.hasInstance
- A method determining if a constructor object recognizes an object as its instance. Used by
instanceof
. Symbol.isConcatSpreadable
- A Boolean value indicating if an object should be flattened to its array elements. Used by
Array.prototype.concat()
. Symbol.unscopables
- An object value of whose own and inherited property names are excluded from the
with
environment bindings of the associated object. Symbol.species
- A constructor function that is used to create derived objects.
Symbol.toPrimitive
- A method converting an object to a primitive value.
Symbol.toStringTag
- A string value used for the default description of an object. Used by
Object.prototype.toString()
.
Methods
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
{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}
Methods
{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}
Examples
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 enumerable 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'});
// '{}'
For more details, see 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
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Symbol' in that specification. |
Standard | Initial definition |
ECMAScript (ECMA-262) The definition of 'Symbol' in that specification. |
Living Standard |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | 38 | 36 (36) | No support | 25 | 9 |
Symbol.iterator (@@iterator) | 38 | 36 (36) | No support | 25 | 9 |
Symbol.unscopables (@@unscopables) | 38 | 48 (48) | No support | 25 | 9 |
Symbol.match (@@match) | 50 | 40 (40) | No support | ? | ? |
Symbol.species (@@species) | 51 | 41 (41) | No support | ? | ? |
Symbol.toPrimitive (@@toPrimitive) | 48 | 44 (44) | No support | ? | ? |
Symbol.replace (@@replace) | 50 | 48 (48) | No support | ? | ? |
Symbol.search (@@search) | 50 | 48 (48) | No support | ? | ? |
Symbol.split (@@split) | 50 | 48 (48) | No support | ? | ? |
Symbol.isConcatSpreadable (@@isconcatspreadable) | 48 | 48 (48) | No support | ? | ? |
Symbol.hasInstance (@@hasInstance) | 51 | 50 (50) | No support | ? | ? |
Symbol.toStringTag (@@toStringTag) | 49 | 51 (51) | No support | ? | ? |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | 38 | 36.0 (36) | No support | 25 | 9 |
Symbol.iterator (@@iterator) | ? | 38 | 36.0 (36) | No support | 25 | 9 |
Symbol.unscopables (@@unscopables) | ? | 38 | 48.0 (48) | No support | 25 | 9 |
Symbol.match (@@match) | ? | ? | 40.0 (40) | No support | ? | ? |
Symbol.species (@@species) | ? | ? | 41.0 (41) | No support | ? | ? |
Symbol.toPrimitive (@@toPrimitive) | ? | ? | 44.0 (44) | No support | ? | ? |
Symbol.replace (@@replace) | ? | ? | 48.0 (48) | No support | ? | ? |
Symbol.search (@@search) | ? | ? | 48.0 (48) | No support | ? | ? |
Symbol.split (@@split) | ? | ? | 48.0 (48) | No support | ? | ? |
Symbol.isConcatSpreadable (@@isconcatspreadable) | ? | ? | 48.0 (48) | No support | ? | ? |
Symbol.hasInstance (@@hasInstance) | ? | ? | 50.0 (50) | No support | ? | ? |
Symbol.toStringTag (@@toStringTag) | ? | ? | 51.0 (51) | No support | ? | ? |