symbol 是一种基本数据类型 (primitive data type)。Symbol()
函数会返回symbol类型的值,该类型具有静态属性和静态方法。它的静态属性会暴露几个内建的成员对象;它的静态方法会暴露全局的symbol注册,且类似于内建对象类,但作为构造函数来说它并不完整,因为它不支持语法:"new Symbol()
"。
每个从Symbol()
返回的symbol值都是唯一的。一个symbol值能作为对象属性的标识符;这是该数据类型仅有的目的。更进一步的解析见—— glossary entry for 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
可选 - 可选的,字符串类型。对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 Boolean
、new 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
orsym | 0
). - 使用宽松相等时,
Object(sym) == sym
returnstrue.
- 这会阻止你从一个 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 |
浏览器兼容性
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Symbol |
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 |
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
|
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
|
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
|
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
|
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
|
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
|
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.