Symbol

 

symbol 是一种基本数据类型 (primitive data type)。Symbol()函数会返回symbol类型的值,该类型具有静态属性和静态方法。它的静态属性会暴露几个内建的成员对象;它的静态方法会暴露全局的symbol注册,且类似于内建对象类,但作为构造函数来说它并不完整,因为它不支持语法:"new Symbol()"。

每个从Symbol()返回的symbol值都是唯一的。一个symbol值能作为对象属性的标识符;这是该数据类型仅有的目的。更进一步的解析见—— glossary entry for Symbol

语法

Symbol([description])

参数

description 可选
可选的,字符串类型。对symbol的描述,可用于调试但不是访问symbol本身。

描述

直接使用Symbol()创建新的symbol类型,并用一个可选的字符串作为其描述。

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

上面的代码创建了三个新的symbol类型。 注意,Symbol("foo") 不会强制将字符串 “foo” 转换成symbol类型。它每次都会创建一个新的 symbol类型:

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

下面带有{jsxref(“Operators/new”,“new”)}运算符的语法将抛出{jsxref(“TypeError”)}错误:

var sym = new Symbol(); // TypeError

这会阻止创建一个显式的 Symbol 包装器对象而不是一个 Symbol 值。围绕原始数据类型创建一个显式包装器对象从 ECMAScript 6 开始不再被支持。 然而,现有的原始包装器对象,如 new Booleannew String以及new Number,因为遗留原因仍可被创建。

如果你真的想创建一个 Symbol 包装器对象 (Symbol wrapper object),你可以使用 Object() 函数:

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

全局共享的 Symbol

上面使用Symbol() 函数的语法,不会在你的整个代码库中创建一个可用的全局?symbol类型。 要创建跨文件可用的symbol,甚至跨域(每个都有它自己的全局作用域) , 使用 Symbol.keyFor() 方法从全局的symbol注册?表设置和取得symbol。

在对象中查找 Symbol 属性

Object.getOwnPropertySymbols() 方法让你在查找一个给定对象的符号属性时返回一个?symbol类型的数组。注意,每个初始化的对象都是没有自己的symbol属性的,因此这个数组可能为空,除非你已经在对象上设置了symbol属性。

属性

Symbol.length
长度属性,值为0。
Symbol.prototype
symbol构造函数的原型。

众所周知的 symbols

除了自己创建的symbol,JavaScript还内建了一些在ECMAScript 5 之前没有暴露给开发者的symbol,它们代表了内部语言行为。它们可以使用以下属性访问:

迭代 symbols

Symbol.iterator
一个返回一个对象默认迭代器的方法。被  for...of 使用。
Symbol.asyncIterator
一个返回对象默认的异步迭代器的方法。被  for await of 使用。

正则表达式 symbols

Symbol.match
一个用于对字符串进行匹配的方法,也用于确定一个对象是否可以作为正则表达式使用。被 String.prototype.match() 使用。
Symbol.replace
一个替换匹配字符串的子串的方法. 被 String.prototype.replace() 使用。
Symbol.search
一个返回一个字符串中与正则表达式相匹配的索引的方法。被 String.prototype.search() 使用。
Symbol.split
一个在匹配正则表达式的索引处拆分一个字符串的方法.。被 String.prototype.split() 使用。

其他 symbols

Symbol.hasInstance
一个确定一个构造器对象识别的对象是否为它的实例的方法。被 instanceof 使用。
Symbol.isConcatSpreadable
一个布尔值,表明一个对象是否应该flattened为它的数组元素。被 Array.prototype.concat() 使用。
Symbol.unscopables
拥有和继承属性名的一个对象的值被排除在与环境绑定的相关对象外。
Symbol.species
一个用于创建派生对象的构造器函数。
Symbol.toPrimitive
一个将对象转化为基本数据类型的方法。
Symbol.toStringTag
用于对象的默认描述的字符串值。被 Object.prototype.toString() 使用。

方法

Symbol.for(key)
使用给定的key搜索现有的symbol,如果找到则返回该symbol。否则将使用给定的key在全局symbol注册表中创建一个新的symbol。
Symbol.keyFor(sym)
从全局symbol注册表中,为给定的symbol检索一个共享的?symbol key。

Symbol 原型

所有 Symbols 继承自 Symbol.prototype.

属性

Symbol.prototype.constructor
返回创建实例原型的函数. 默认为  Symbol 函数。
Symbol.prototype.description
一个包含symbol描述的只读字符串。

方法

Symbol.prototype.toSource()
返回包含 Symbol 对象源码的字符串。覆盖 Object.prototype.toSource() 方法。
Symbol.prototype.toString()
返回包含Symbol描述符的字符串。 覆盖 Object.prototype.toString() 方法。
Symbol.prototype.valueOf()
返回 Symbol 对象的初始值.。覆盖 Object.prototype.valueOf() 方法。
Symbol.prototype[@@toPrimitive]
 返回 Symbol对象的初始值。

示例

对 symbol 使用 typeof 运算符

 typeof运算符能帮助你识别 symbol 类型

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

Symbol 类型转换

当使用 symbol 值进行类型转换时需要注意一些事情:

  • 尝试将一个 symbol 值转换为一个 number 值时,会抛出一个 TypeError 错误  (e.g. +sym or sym | 0).
  • 使用宽松相等时, Object(sym) == sym returns true.
  • 这会阻止你从一个 symbol 值隐式地创建一个新的 string 类型的属性名。例如,Symbol("foo") + "bar" 将抛出一个 TypeError (can't convert symbol to string).
  • "safer" String(sym) conversion 的作用会像symbol类型调用 Symbol.prototype.toString() 一样,但是注意 new String(sym) 将抛出异常。

Symbols 与 for...in 迭代

Symbols 在 for...in 迭代中不可枚举。另外,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); // logs "c" and "d"
}

Symbols 与 JSON.stringify()

当使用 JSON.strIngify() 时,以 symbol 值作为键的属性会被完全忽略:

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

更多细节,请看 JSON.stringify()

Symbol 包装器对象作为属性的键

当一个 Symbol 包装器对象作为一个属性的键时,这个对象将被强制转换为它包装过的 symbol 值:

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

规范

标准 状态 注释
ECMAScript 2015 (6th Edition, ECMA-262)
Symbol
Standard 原始定义
ECMAScript Latest Draft (ECMA-262)
Symbol
Draft

浏览器兼容性

Update compatibility data on GitHub
Desktop Mobile Server
Chrome Edge Firefox Internet Explorer Opera Safari Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet Node.js
Symbol Chrome Full support 38 Edge Full support 12
Notes
Full support 12
Notes
Notes Edge 12 included Symbol properties in JSON.stringify() output.
Firefox Full support 36 IE No support No Opera Full support 25 Safari Full support 9 WebView Android Full support 38 Chrome Android Full support 38 Firefox Android Full support 36 Opera Android Full support 25 Safari iOS Full support 9 Samsung Internet Android Full support 3.0 nodejs Full support Yes
asyncIterator Chrome Full support 63 Edge No support No Firefox Full support 57 IE No support No Opera Full support 50 Safari Full support 11.1 WebView Android Full support 63 Chrome Android Full support 63 Firefox Android No support No Opera Android Full support 46 Safari iOS No support No Samsung Internet Android Full support 8.0 nodejs Full support 10.0.0
description Chrome Full support 70 Edge No support No Firefox Full support 63 IE No support No Opera Full support 57 Safari Full support 12.1
Full support 12.1
Partial support 12
Notes
Notes No support for an undefined description.
WebView Android Full support 70 Chrome Android Full support 70 Firefox Android Full support 63 Opera Android Full support 49 Safari iOS Full support 12.2
Full support 12.2
Partial support 12
Notes
Notes No support for an undefined description.
Samsung Internet Android Full support 10.0 nodejs Full support 11.0.0
for Chrome Full support 40 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support Yes Safari Full support 9 WebView Android Full support 40 Chrome Android Full support 40 Firefox Android Full support 36 Opera Android Full support Yes Safari iOS Full support 9 Samsung Internet Android Full support 4.0 nodejs Full support Yes
hasInstance Chrome Full support 50 Edge Full support 15 Firefox Full support 50 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 50 Chrome Android Full support 50 Firefox Android Full support 50 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.5.0
Full support 6.5.0
Full support 6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadable Chrome Full support 48 Edge Full support 15 Firefox Full support 48 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 48 Chrome Android Full support 48 Firefox Android Full support 48 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
iterator Chrome Full support 43 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support 30 Safari Full support 10 WebView Android Full support 43 Chrome Android Full support 43 Firefox Android Full support 36 Opera Android Full support Yes Safari iOS Full support 10 Samsung Internet Android Full support 4.0 nodejs Full support 0.12
keyFor Chrome Full support 40 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support Yes Safari Full support 9 WebView Android Full support 40 Chrome Android Full support 40 Firefox Android Full support 36 Opera Android Full support Yes Safari iOS Full support 9 Samsung Internet Android Full support 4.0 nodejs Full support Yes
match Chrome Full support 50 Edge No support No Firefox Full support 40 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 50 Chrome Android Full support 50 Firefox Android Full support 40 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
matchAll Chrome Full support 73 Edge No support No Firefox Full support 67 IE No support No Opera Full support 60 Safari No support No WebView Android Full support 73 Chrome Android Full support 73 Firefox Android Full support 67 Opera Android Full support Yes Safari iOS No support No Samsung Internet Android No support No nodejs Full support 12.0.0
prototype Chrome Full support 38 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support 25 Safari Full support 9 WebView Android Full support 38 Chrome Android Full support 38 Firefox Android Full support 36 Opera Android Full support 25 Safari iOS Full support 9 Samsung Internet Android Full support 3.0 nodejs Full support Yes
replace Chrome Full support 50 Edge No support No Firefox Full support 49 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 50 Chrome Android Full support 50 Firefox Android Full support 49 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
search Chrome Full support 50 Edge No support No Firefox Full support 49 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 50 Chrome Android Full support 50 Firefox Android Full support 49 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
species Chrome Full support 51 Edge Full support 13 Firefox Full support 41 IE No support No Opera Full support 38 Safari Full support 10 WebView Android Full support 51 Chrome Android Full support 51 Firefox Android Full support 41 Opera Android Full support 41 Safari iOS Full support 10 Samsung Internet Android Full support 5.0 nodejs Full support 6.5.0
Full support 6.5.0
Full support 6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
split Chrome Full support 50 Edge No support No Firefox Full support 49 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 50 Chrome Android Full support 50 Firefox Android Full support 49 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
toPrimitive Chrome Full support 47 Edge Full support 15 Firefox Full support 44 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 47 Chrome Android Full support 47 Firefox Android Full support 44 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
toSource
Non-standard
Chrome No support No Edge No support No Firefox Full support 36 IE No support No Opera No support No Safari No support No WebView Android No support No Chrome Android No support No Firefox Android Full support 36 Opera Android No support No Safari iOS No support No Samsung Internet Android No support No nodejs No support No
toString Chrome Full support 38 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support 25 Safari Full support 9 WebView Android Full support 38 Chrome Android Full support 38 Firefox Android Full support 36 Opera Android Full support 25 Safari iOS Full support 9 Samsung Internet Android Full support 3.0 nodejs Full support Yes
toStringTag Chrome Full support 49 Edge Full support 15 Firefox Full support 51 IE No support No Opera Full support Yes Safari Full support Yes WebView Android Full support 49 Chrome Android Full support 49 Firefox Android Full support 51 Opera Android Full support Yes Safari iOS Full support Yes Samsung Internet Android Full support 5.0 nodejs Full support 6.0.0
Full support 6.0.0
Full support 4.0.0
Disabled
Disabled From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopables Chrome Full support 45 Edge Full support 12 Firefox Full support 48 IE No support No Opera Full support Yes Safari Full support 9 WebView Android Full support 45 Chrome Android Full support 45 Firefox Android Full support 48 Opera Android Full support Yes Safari iOS Full support 9 Samsung Internet Android Full support 5.0 nodejs Full support 0.12
valueOf Chrome Full support 38 Edge Full support 12 Firefox Full support 36 IE No support No Opera Full support 25 Safari Full support 9 WebView Android Full support 38 Chrome Android Full support 38 Firefox Android Full support 36 Opera Android Full support 25 Safari iOS Full support 9 Samsung Internet Android Full support 3.0 nodejs Full support Yes
@@toPrimitive Chrome Full support 47 Edge Full support 15 Firefox Full support 44 IE No support No Opera Full support 34 Safari ? WebView Android Full support 47 Chrome Android Full support 47 Firefox Android Full support 44 Opera Android Full support 34 Safari iOS ? Samsung Internet Android Full support 5.0 nodejs ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

参考文档