Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

Сводка

Символ (анг. Symbol) — это уникальный и неизменяемый тип данных, который может быть использован как идентификатор для свойств объектов. Символьный объект (анг. symbol object) — это объект-обёртка (англ. wrapper) для примитивного символьного типа.

Синтаксис

Symbol([описание])

Параметры

описание Необязательный
Необязательный, строка. Описание символа, которое может быть использовано во время отладки, но не для доступа к самому символу.

Описание

Чтобы создать новый символьный примитив, достаточно написать Symbol(), указав по желанию строку в качестве описания этого символа:

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

Код выше создает три новых символа. Заметьте, что Symbol("foo") не выполняет приведение (англ. coercion) строки "foo" к символу. Это выражение создает каждый раз новый символ:

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

Код ниже с оператором new бросит исключение TypeError:

var sym = new Symbol(); // TypeError

Это удерживает разработчиков от создания явного объекта-обёртки Symbol вместо нового символьного значения. Создание явных объектов-обёрток для примитивных типов доступно (например, new Boolean, new String, new Number).

Если вам действительно необходимо обернуть символ в объект, вы можете использовать функцию Object():

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

Разделяемые символы в глобальном символьном реестре

Приведенный выше синтаксис, использующий функцию Symbol(), не создаст глобальный символ, который был бы доступен в любом месте вашего кода. Для создания символов, доступных во всех файлах и в окружении (глобальной области), используйте методы Symbol.for() и Symbol.keyFor(), чтобы задать или получить символ из глобального символьного реестра.

Поиск символьных свойств у объектов

Метод Object.getOwnPropertySymbols() возвращает массив символов и позволяет получить символьные свойства конкретного объекта. Следует заметить, что при инициализации объекты не получают символьных свойств, так что этот массив будет пуст, пока вы не зададите ему какое-либо символьное свойство.

Свойства

Symbol.length
Содержит длину, всегда равную 0 (нулю).
Symbol.prototype
Содержит прототип конструктора Symbol.

Известные символы

В добавок к вашим собственным символам, JavaScript имеет несколько встроенных символов, представляющих внутренние механизмы языка, которые не были доступны разработчикам в версиях ECMAScript 5 и более ранних. Эти символы доступны посредством следующих свойств:

Итерационные символы

Symbol.iterator
Метод, возвращающий итератор по умолчанию для объекта. Используется конструкцией for...of.

Символы регулярных выражений

Symbol.match
Метод для сопоставления объекта со строкой, также используемый для определения возможности объекта выступать в качестве регулярного выражения. Используется функцией String.prototype.match().
Symbol.replace
Метод, заменяющий совпавшие подстроки в строке. Используется функцией String.prototype.replace().
Symbol.search
Метод, возвращающий индекс вхождения подстроки, соответствующей регулярному выражению. Используется функцией String.prototype.search().
Symbol.split
Метод, разбивающий строку на части в местах, соответствующих регулярному выражению. Используется функцией String.prototype.split()

Другие символы

Symbol.hasInstance
Метод, определяющий, распознает ли конструктор некоторый объект как свой экземпляр. Используется оператором instanceof.
Symbol.isConcatSpreadable
Булево значение, показывающее, должен ли объект быть сведен к плоскому представлению (англ. flatten) в виде массива его элементов функцией Array.prototype.concat().
Symbol.unscopables
Массив строковых имен свойств. Позволяет скрыть свойства от инструкции with (прежде всего для обратной совместимости).
Symbol.species
Метод, определяющий конструктор для порождённых объектов.
Symbol.toPrimitive
Метод, преобразующий объект в примитив (примитивное значение).
Symbol.toStringTag
Строковое значение, используемое в качестве описания объекта по умолчанию. Используется функцией Object.prototype.toString()

Методы

Symbol.for(key)
Ищет существующие символы по заданному ключу и возвращает его, если он найден. В противном случае создается новый символ для данного ключа в глобальном реестре символов.
Symbol.keyFor(sym)
Получает по разделямому символу его ключ из глобального реестра символов.

Прототип Symbol

Все символы наследуют от Symbol.prototype.

Свойства

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.

Методы

Symbol.prototype.toSource()
Returns a string containing the source of the Symbol object. Overrides the Object.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 the Object.prototype.valueOf() method.
Symbol.prototype[@@toPrimitive]
Returns the primitive value of the Symbol object.

Примеры

Использование оператора typeof с символами

Оператор typeof позволяет идентифицировать символ.

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

Преобразование типов с символами

Следующее необходимо помнить при преобразовании типа символов.

  • При попытке конвертировать символ в число, будет брошено исключение TypeError (напр., +sym или sym | 0).
  • Результатом нестрогого сравнения, Object(sym) == sym, будет true.
  • Symbol("foo") + "bar" бросает исключение TypeError (невозможно преобразовать символ в строку). Это удерживает разработчика от, к примеру, случайного создания строкого поля у объекта из символа.
  • Более  "безопасный" вызов String(sym) работает с символами как вызов Symbol.prototype.toString(). Заметьте, что в то же время new String(sym) бросит исключение.

Символы и конструкция for...in

Символы не перечисляются при итерации for...in. В дополнение к этому, Object.getOwnPropertyNames() не вернет символьные свойства объекта. Тем не менее, их можно получить с помощью Object.getOwnPropertySymbols().

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); // выведет "c" и "d"
}

Символы и JSON.stringify()

JSON.stringify() игнорирует свойства с ключами Symbol:

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

Подробности см. JSON.stringify().

Объекты-обёртки для Symbol в качестве имен свойств

Когда объект-обёртка символа используется в качестве имени свойства, этот объект сводится к символу, который он оборачивает:

var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // снова 1

Спецификации

Спецификация Статус Комментарий
ECMAScript 2015 (6th Edition, ECMA-262)
Определение 'Symbol' в этой спецификации.
Стандарт Изначальное определение
ECMAScript Latest Draft (ECMA-262)
Определение 'Symbol' в этой спецификации.
Черновик  

Поддержка браузерами

 

Update compatibility data on GitHub
КомпьютерыМобильныеServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome для AndroidEdge MobileFirefox для AndroidOpera для AndroidSafari on iOSSamsung InternetNode.js
SymbolChrome Полная поддержка 38Edge Полная поддержка 12
Замечания
Полная поддержка 12
Замечания
Замечания Edge 12 included Symbol properties in JSON.stringify() output.
Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка 25Safari Полная поддержка 9WebView Android Полная поддержка 38Chrome Android Полная поддержка 38Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка 25Safari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
asyncIteratorChrome Полная поддержка 63Edge Нет поддержки НетFirefox Полная поддержка 57IE Нет поддержки НетOpera Полная поддержка 50Safari Полная поддержка 11.1WebView Android Полная поддержка 63Chrome Android Полная поддержка 63Edge Mobile Нет поддержки НетFirefox Android Нет поддержки НетOpera Android Полная поддержка 46Safari iOS Нет поддержки НетSamsung Internet Android Нет поддержки Нетnodejs Полная поддержка 10.0.0
descriptionChrome Полная поддержка 70Edge Нет поддержки НетFirefox Полная поддержка 63IE Нет поддержки НетOpera Полная поддержка 57Safari Полная поддержка 12.1
Полная поддержка 12.1
Частичная поддержка 12
Замечания
Замечания No support for an undefined description.
WebView Android Полная поддержка 70Chrome Android Полная поддержка 70Edge Mobile Нет поддержки НетFirefox Android Полная поддержка 63Opera Android Полная поддержка 49Safari iOS Полная поддержка 12.2
Полная поддержка 12.2
Частичная поддержка 12
Замечания
Замечания No support for an undefined description.
Samsung Internet Android Нет поддержки Нетnodejs Нет поддержки Нет
forChrome Полная поддержка 40Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка 9WebView Android Полная поддержка 40Chrome Android Полная поддержка 40Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка ДаSafari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
hasInstanceChrome Полная поддержка 50Edge Полная поддержка 15Firefox Полная поддержка 50IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 50Chrome Android Полная поддержка 50Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 50Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.5.0
Полная поддержка 6.5.0
Полная поддержка 6.0.0
Отключено
Отключено From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadableChrome Полная поддержка 48Edge Полная поддержка 15Firefox Полная поддержка 48IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 48Chrome Android Полная поддержка 48Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 48Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
iteratorChrome Полная поддержка 43Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка 30Safari Полная поддержка 10WebView Android Полная поддержка 43Chrome Android Полная поддержка 43Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка ДаSafari iOS Полная поддержка 10Samsung Internet Android Полная поддержка Даnodejs Полная поддержка 0.12
keyForChrome Полная поддержка 40Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка 9WebView Android Полная поддержка 40Chrome Android Полная поддержка 40Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка ДаSafari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
matchChrome Полная поддержка 50Edge Полная поддержка ДаFirefox Полная поддержка 40IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 50Chrome Android Полная поддержка 50Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 40Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
matchAllChrome Полная поддержка 73Edge Нет поддержки НетFirefox Полная поддержка 67IE Нет поддержки НетOpera Полная поддержка 60Safari Нет поддержки НетWebView Android Полная поддержка 73Chrome Android Полная поддержка 73Edge Mobile Нет поддержки НетFirefox Android Полная поддержка 67Opera Android Полная поддержка ДаSafari iOS Нет поддержки НетSamsung Internet Android Полная поддержка Даnodejs Нет поддержки Нет
prototypeChrome Полная поддержка 38Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка 25Safari Полная поддержка 9WebView Android Полная поддержка 38Chrome Android Полная поддержка 38Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка 25Safari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
replaceChrome Полная поддержка 50Edge Полная поддержка ДаFirefox Полная поддержка 49IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 50Chrome Android Полная поддержка 50Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 49Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
searchChrome Полная поддержка 50Edge Полная поддержка ДаFirefox Полная поддержка 49IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 50Chrome Android Полная поддержка 50Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 49Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
speciesChrome Полная поддержка 51Edge Полная поддержка 13Firefox Полная поддержка 41IE Нет поддержки НетOpera Полная поддержка 38Safari Полная поддержка 10WebView Android Полная поддержка 51Chrome Android Полная поддержка 51Edge Mobile Полная поддержка 14Firefox Android Полная поддержка 41Opera Android Полная поддержка 41Safari iOS Полная поддержка 10Samsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.5.0
Полная поддержка 6.5.0
Полная поддержка 6.0.0
Отключено
Отключено From version 6.0.0: this feature is behind the --harmony runtime flag.
splitChrome Полная поддержка 50Edge Полная поддержка ДаFirefox Полная поддержка 49IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 50Chrome Android Полная поддержка 50Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 49Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
toPrimitiveChrome Полная поддержка 47Edge Полная поддержка 15Firefox Полная поддержка 44IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 47Chrome Android Полная поддержка 47Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 44Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
toSource
Нестандартная
Chrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 36IE Нет поддержки НетOpera Нет поддержки НетSafari Нет поддержки НетWebView Android Нет поддержки НетChrome Android Нет поддержки НетEdge Mobile Нет поддержки НетFirefox Android Полная поддержка 36Opera Android Нет поддержки НетSafari iOS Нет поддержки НетSamsung Internet Android Нет поддержки Нетnodejs Нет поддержки Нет
toStringChrome Полная поддержка 38Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка 25Safari Полная поддержка 9WebView Android Полная поддержка 38Chrome Android Полная поддержка 38Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка 25Safari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
toStringTagChrome Полная поддержка 49Edge Полная поддержка 15Firefox Полная поддержка 51IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка 49Chrome Android Полная поддержка 49Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 51Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Даnodejs Полная поддержка 6.0.0
Полная поддержка 6.0.0
Полная поддержка 4.0.0
Отключено
Отключено From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopablesChrome Полная поддержка 45Edge Полная поддержка 12Firefox Полная поддержка 48IE Нет поддержки НетOpera Полная поддержка ДаSafari Полная поддержка 9WebView Android Полная поддержка 45Chrome Android Полная поддержка 45Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 48Opera Android Полная поддержка ДаSafari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка 0.12
valueOfChrome Полная поддержка 38Edge Полная поддержка 12Firefox Полная поддержка 36IE Нет поддержки НетOpera Полная поддержка 25Safari Полная поддержка 9WebView Android Полная поддержка 38Chrome Android Полная поддержка 38Edge Mobile Полная поддержка ДаFirefox Android Полная поддержка 36Opera Android Полная поддержка 25Safari iOS Полная поддержка 9Samsung Internet Android Полная поддержка Даnodejs Полная поддержка Да
@@toPrimitiveChrome ? Edge ? Firefox Полная поддержка 44IE Нет поддержки НетOpera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android Полная поддержка 44Opera Android ? Safari iOS ? Samsung Internet Android ? nodejs ?

Легенда

Полная поддержка  
Полная поддержка
Нет поддержки  
Нет поддержки
Совместимость неизвестна  
Совместимость неизвестна
Нестандартная. Ожидается плохая кросс-браузерная поддержка.
Нестандартная. Ожидается плохая кросс-браузерная поддержка.
Смотрите замечания реализации.
Смотрите замечания реализации.
Пользователь должен сам включить эту возможность.
Пользователь должен сам включить эту возможность.

См. также

Метки документа и участники

Внесли вклад в эту страницу: boxa6, mdnwebdocs-bot, pk.prog, smurf, neutral, schyzoo
Обновлялась последний раз: boxa6,