1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
---
title: Symbol
slug: Web/JavaScript/Reference/Global_Objects/Symbol
tags:
- ECMAScript6
- JavaScript
- Symbol
translation_of: Web/JavaScript/Reference/Global_Objects/Symbol
---
<div>{{JSRef}} </div>
<p><strong>symbol</strong> 是一种基本数据类型 （{{Glossary("Primitive", "primitive data type")}}）。<code>Symbol()</code>函数会返回<strong>symbol</strong>类型的值，该类型具有静态属性和静态方法。它的静态属性会暴露几个内建的成员对象；它的静态方法会暴露全局的symbol注册，且类似于内建对象类，但作为构造函数来说它并不完整，因为它不支持语法："<code>new Symbol()</code>"。</p>
<p>每个从<code>Symbol()</code>返回的symbol值都是唯一的。一个symbol值能作为对象属性的标识符；这是该数据类型仅有的目的。更进一步的解析见—— <a href="https://developer.mozilla.org/en-US/docs/Glossary/Symbol">glossary entry for Symbol</a>。</p>
<div>{{EmbedInteractiveExample("pages/js/symbol-constructor.html")}}</div>
<h2 id="Syntax" name="Syntax">语法</h2>
<pre class="syntaxbox notranslate"><code>Symbol(<em>[description]</em>)</code></pre>
<h3 id="Parameters" name="Parameters">参数</h3>
<dl>
<dt><code>description</code> {{optional_inline}}</dt>
<dd>可选的，字符串类型。对symbol的描述，可用于调试但不是访问symbol本身。</dd>
</dl>
<h2 id="Description" name="Description">描述</h2>
<p>直接使用<code>Symbol()</code>创建新的symbol类型，并用一个可选的字符串作为其描述。</p>
<pre class="brush: js notranslate">var sym1 = Symbol();
var sym2 = Symbol('foo');
var sym3 = Symbol('foo');
</pre>
<p>上面的代码创建了三个新的symbol类型。 注意，<code>Symbol("foo")</code> 不会强制将字符串 “foo” 转换成symbol类型。它每次都会创建一个新的 symbol类型：</p>
<pre class="brush: js notranslate">Symbol("foo") === Symbol("foo"); // false</pre>
<p>下面带有 {{jsxref("Operators/new", "new")}} 运算符的语法将抛出 {{jsxref("TypeError")}} 错误：</p>
<pre class="brush: js notranslate">var sym = new Symbol(); // TypeError</pre>
<p>这会阻止创建一个显式的 Symbol 包装器对象而不是一个 Symbol 值。围绕原始数据类型创建一个显式包装器对象从 ECMAScript 6 开始不再被支持。 然而，现有的原始包装器对象，如 <code style="font-style: normal;">new Boolean</code>、<code style="font-style: normal;">new String</code>以及<span style="font-family: consolas,monaco,andale mono,monospace;"><code>new Number</code>，因为遗留原因仍可被创建。</span></p>
<p>如果你真的想创建一个 <u>Symbol 包装器对象 </u>(<code>Symbol wrapper object</code>)，你可以使用 <code>Object()</code> 函数：</p>
<pre class="brush: js notranslate">var sym = Symbol("foo");
typeof sym; // "symbol"
var symObj = Object(sym);
typeof symObj; // "object"</pre>
<h3 id="全局共享的_Symbol">全局共享的 Symbol</h3>
<p>上面使用<code>Symbol()</code> 函数的语法，不会在你的整个代码库中创建一个可用的全局的symbol类型。 要创建跨文件可用的symbol，甚至跨域（每个都有它自己的全局作用域） , 使用 {{jsxref("Symbol.for()")}} 方法和 {{jsxref("Symbol.keyFor()")}} 方法从全局的symbol注册表设置和取得symbol。</p>
<h3 id="在对象中查找_Symbol_属性">在对象中查找 Symbol 属性</h3>
<p>{{jsxref("Object.getOwnPropertySymbols()")}} 方法让你在查找一个给定对象的符号属性时返回一个symbol类型的数组。注意，每个初始化的对象都是没有自己的symbol属性的，因此这个数组可能为空，除非你已经在对象上设置了symbol属性。</p>
<h2 id="Properties" name="Properties">属性</h2>
<dl>
<dt><code>Symbol.length</code></dt>
<dd>长度属性，值为0。</dd>
<dt>{{jsxref("Symbol.prototype")}}</dt>
<dd><code>symbol</code>构造函数的原型。</dd>
</dl>
<h3 id="众所周知的_symbols">众所周知的 symbols</h3>
<p>除了自己创建的symbol，JavaScript还内建了一些在ECMAScript 5 之前没有暴露给开发者的symbol，它们代表了内部语言行为。它们可以使用以下属性访问：</p>
<dl>
<dt>
<h4 id="迭代_symbols">迭代 symbols</h4>
</dt>
<dt>{{jsxref("Symbol.iterator")}}</dt>
<dd>一个返回一个对象默认迭代器的方法。被 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of">for...of</a></code> 使用。</dd>
<dt>{{jsxref("Symbol.asyncIterator")}} {{experimental_inline}}</dt>
<dd>一个返回对象默认的异步迭代器的方法。被 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of">for await of</a></code> 使用。</dd>
<dt>
<h4 id="正则表达式_symbols">正则表达式 symbols</h4>
</dt>
<dt>{{jsxref("Symbol.match")}}</dt>
<dd>一个用于对字符串进行匹配的方法，也用于确定一个对象是否可以作为正则表达式使用。被 {{jsxref("String.prototype.match()")}} 使用。</dd>
<dt>{{jsxref("Symbol.replace")}}</dt>
<dd>一个替换匹配字符串的子串的方法. 被 {{jsxref("String.prototype.replace()")}} 使用。</dd>
<dt>{{jsxref("Symbol.search")}}</dt>
<dd>一个返回一个字符串中与正则表达式相匹配的索引的方法。被{{jsxref("String.prototype.search()")}} 使用。</dd>
<dt>{{jsxref("Symbol.split")}}</dt>
<dd>一个在匹配正则表达式的索引处拆分一个字符串的方法.。被 {{jsxref("String.prototype.split()")}} 使用。</dd>
<dt>
<h4 id="其他_symbols">其他 symbols</h4>
</dt>
<dt>{{jsxref("Symbol.hasInstance")}}</dt>
<dd>一个确定一个构造器对象识别的对象是否为它的实例的方法。被 {{jsxref("Operators/instanceof", "instanceof")}} 使用。</dd>
<dt>{{jsxref("Symbol.isConcatSpreadable")}}</dt>
<dd>一个布尔值，表明一个对象是否应该flattened为它的数组元素。被 {{jsxref("Array.prototype.concat()")}} 使用。</dd>
<dt>{{jsxref("Symbol.unscopables")}}</dt>
<dd>拥有和继承属性名的一个对象的值被排除在与环境绑定的相关对象外。</dd>
<dt>{{jsxref("Symbol.species")}}</dt>
<dd>一个用于创建派生对象的构造器函数。</dd>
<dt>{{jsxref("Symbol.toPrimitive")}}</dt>
<dd>一个将对象转化为基本数据类型的方法。</dd>
<dt>{{jsxref("Symbol.toStringTag")}}</dt>
<dd>用于对象的默认描述的字符串值。被 {{jsxref("Object.prototype.toString()")}} 使用。</dd>
</dl>
<h2 id="Methods" name="Methods">方法</h2>
<dl>
<dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt>
<dd>使用给定的key搜索现有的symbol，如果找到则返回该symbol。否则将使用给定的key在全局symbol注册表中创建一个新的symbol。</dd>
<dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt>
<dd>从全局symbol注册表中，为给定的symbol检索一个共享的?symbol key。</dd>
</dl>
<h2 id="Boolean_instances" name="Boolean_instances"><font face="Consolas, Monaco, Andale Mono, monospace">Symbol 原型</font></h2>
<p>所有 Symbols 继承自 {{jsxref("Symbol.prototype")}}.</p>
<h3 id="属性">属性</h3>
<p>{{page('zh-CN/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}</p>
<h3 id="方法">方法</h3>
<p>{{page('zh-CN/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}</p>
<h2 id="Examples" name="Examples">示例</h2>
<h3 id="Creating_Boolean_objects_with_an_initial_value_of_false" name="Creating_Boolean_objects_with_an_initial_value_of_false">对 symbol 使用 typeof 运算符</h3>
<p> {{jsxref("Operators/typeof", "typeof")}}运算符能帮助你识别 symbol 类型</p>
<pre class="brush: js notranslate"><code class="language-js"><span class="keyword token">typeof</span> <span class="function token">Symbol<span class="punctuation token">(</span></span><span class="punctuation token">)</span> <span class="operator token">==</span><span class="operator token">=</span> <span class="string token">'symbol'</span>
<span class="keyword token">typeof</span> <span class="function token">Symbol<span class="punctuation token">(</span></span><span class="string token">'foo'</span><span class="punctuation token">)</span> <span class="operator token">==</span><span class="operator token">=</span> <span class="string token">'symbol'</span>
<span class="keyword token">typeof</span> Symbol<span class="punctuation token">.</span>iterator <span class="operator token">==</span><span class="operator token">=</span> <span class="string token">'symbol'</span></code>
</pre>
<h3 id="Symbol_类型转换">Symbol 类型转换</h3>
<p>当使用 symbol 值进行类型转换时需要注意一些事情：</p>
<ul>
<li>尝试将一个 symbol 值转换为一个 number 值时，会抛出一个 {{jsxref("TypeError")}} 错误 (e.g. <code>+sym</code> or <code>sym | 0</code>).</li>
<li>使用宽松相等时， <code>Object(sym) == sym</code> returns <code>true.</code></li>
<li>这会阻止你从一个 symbol 值隐式地创建一个新的 string 类型的属性名。例如，<code>Symbol("foo") + "bar" 将抛出一个</code> {{jsxref("TypeError")}} (can't convert symbol to string).</li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"safer" <code>String(sym)</code> conversion</a> 的作用会像symbol类型调用 {{jsxref("Symbol.prototype.toString()")}} 一样，但是注意 <code>new String(sym)</code> 将抛出异常。</li>
</ul>
<h3 id="Symbols_与_for...in_迭代">Symbols 与 <code>for...in</code> 迭代</h3>
<p>Symbols 在 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...in"><code>for...in</code></a> 迭代中不可枚举。另外，{{jsxref("Object.getOwnPropertyNames()")}} 不会返回 symbol 对象的属性，但是你能使用 {{jsxref("Object.getOwnPropertySymbols()")}} 得到它们。</p>
<pre class="brush: js line-numbers language-js notranslate"><code class="language-js"><span class="keyword token">var</span> obj <span class="operator token">=</span> <span class="punctuation token">{</span><span class="punctuation token">}</span><span class="punctuation token">;</span>
obj<span class="punctuation token">[</span><span class="function token">Symbol</span><span class="punctuation token">(</span><span class="string token">"a"</span><span class="punctuation token">)</span><span class="punctuation token">]</span> <span class="operator token">=</span> <span class="string token">"a"</span><span class="punctuation token">;</span>
obj<span class="punctuation token">[</span>Symbol<span class="punctuation token">.</span><span class="keyword token">for</span><span class="punctuation token">(</span><span class="string token">"b"</span><span class="punctuation token">)</span><span class="punctuation token">]</span> <span class="operator token">=</span> <span class="string token">"b"</span><span class="punctuation token">;</span>
obj<span class="punctuation token">[</span><span class="string token">"c"</span><span class="punctuation token">]</span> <span class="operator token">=</span> <span class="string token">"c"</span><span class="punctuation token">;</span>
obj<span class="punctuation token">.</span>d <span class="operator token">=</span> <span class="string token">"d"</span><span class="punctuation token">;</span>
<span class="keyword token">for</span> <span class="punctuation token">(</span><span class="keyword token">var</span> i <span class="keyword token">in</span> obj<span class="punctuation token">)</span> <span class="punctuation token">{</span>
console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>i<span class="punctuation token">)</span><span class="punctuation token">;</span> <span class="comment token">// logs "c" and "d"</span>
<span class="punctuation token">}</span></code></pre>
<h3 id="Symbols_与_JSON.stringify">Symbols 与 <code>JSON.stringify()</code></h3>
<p>当使用 JSON.stringify() 时，以 symbol 值作为键的属性会被完全忽略：</p>
<pre class="brush: js notranslate"><code class="language-js">JSON<span class="punctuation token">.</span><span class="function token">stringify</span><span class="punctuation token">(</span><span class="punctuation token">{</span><span class="punctuation token">[</span><span class="function token">Symbol</span><span class="punctuation token">(</span><span class="string token">"foo"</span><span class="punctuation token">)</span><span class="punctuation token">]</span><span class="punctuation token">:</span> <span class="string token">"foo"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
<span class="comment token">// '{}'</span></code></pre>
<p>更多细节，请看 {{jsxref("JSON.stringify()")}}。</p>
<h3 id="Symbol_包装器对象作为属性的键">Symbol 包装器对象作为属性的键</h3>
<p>当一个 Symbol 包装器对象作为一个属性的键时，这个对象将被强制转换为它包装过的 symbol 值：</p>
<pre class="brush: js notranslate"><code class="language-js"><span class="keyword token">var</span> sym <span class="operator token">=</span> <span class="function token">Symbol</span><span class="punctuation token">(</span><span class="string token">"foo"</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
<span class="keyword token">var</span> obj <span class="operator token">=</span> <span class="punctuation token">{</span><span class="punctuation token">[</span>sym<span class="punctuation token">]</span><span class="punctuation token">:</span> <span class="number token">1</span><span class="punctuation token">}</span><span class="punctuation token">;</span>
obj<span class="punctuation token">[</span>sym<span class="punctuation token">]</span><span class="punctuation token">;</span> <span class="comment token">// 1</span>
obj<span class="punctuation token">[</span><span class="function token">Object</span><span class="punctuation token">(</span>sym<span class="punctuation token">)</span><span class="punctuation token">]</span><span class="punctuation token">;</span> <span class="comment token">// still 1</span></code></pre>
<h2 id="规范">规范</h2>
<table class="standard-table" style="height: 143px; width: 640px;">
<tbody>
<tr>
<th scope="col">标准</th>
<th scope="col">状态</th>
<th scope="col">注释</th>
</tr>
<tr>
<td>{{SpecName('ES6', '#sec-symbol-objects', 'Symbol')}}</td>
<td>{{Spec2('ES6')}}</td>
<td>原始定义</td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<p>{{Compat("javascript.builtins.Symbol")}}</p>
<h2 id="参考文档">参考文档</h2>
<ul>
<li><a href="/en-US/docs/Glossary/Symbol">Glossary: Symbol data type</a></li>
<li>{{jsxref("Operators/typeof", "typeof")}}</li>
<li><a href="/en-US/docs/Web/JavaScript/Data_structures">Data types and data structures</a></li>
<li><a href="https://hacks.mozilla.org/2015/06/es6-in-depth-symbols/">"ES6 In Depth: Symbols"（深入ES6 Symbols ） on hacks.mozilla.org</a></li>
</ul>
<div class="itanywhere-activator" style="left: 41px; top: 3679px; display: none;" title="Google Translator Anywhere"></div>
|
