符合

¥Description

要创建新的原始符号，请编写 Symbol() 并使用可选字符串作为其描述：

¥To create a new primitive Symbol, you write Symbol() with an optional string as its description:

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

上面的代码创建了三个新的符号。请注意，Symbol("foo") 不会将字符串 "foo" 强制转换为符号。它每次都会创建一个新的符号：

¥The above code creates three new Symbols. Note that Symbol("foo") does not coerce the string "foo" into a Symbol. It creates a new Symbol each time:

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

以下带有 new 运算符的语法将抛出 TypeError：

¥The following syntax with the new operator will throw a TypeError:

const sym = new Symbol(); // TypeError

这会阻止作者创建显式 Symbol 封装器对象而不是新的 Symbol 值，并且可能会令人惊讶，因为通常可以围绕原始数据类型创建显式封装器对象（例如 new Boolean、new String 和 new Number）。

¥This prevents authors from creating an explicit Symbol wrapper object instead of a new Symbol value and might be surprising as creating explicit wrapper objects around primitive data types is generally possible (for example, new Boolean, new String and new Number).

如果你确实想创建 Symbol 封装对象，可以使用 Object() 函数：

¥If you really want to create a Symbol wrapper object, you can use the Object() function:

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

由于符号是唯一具有引用标识的原始数据类型（即，你不能两次创建相同的符号），因此它们在某种程度上表现得像对象。例如，它们是可垃圾收集的，因此可以存储在 WeakMap、WeakSet、WeakRef 和 FinalizationRegistry 对象中。

¥Because symbols are the only primitive data type that has reference identity (that is, you cannot create the same symbol twice), they behave like objects in some way. For example, they are garbage collectable and can therefore be stored in WeakMap, WeakSet, WeakRef, and FinalizationRegistry objects.

¥Shared Symbols in the global Symbol registry

使用 Symbol() 函数的上述语法将创建一个符号，其值在程序的整个生命周期中保持唯一。要创建跨文件甚至跨字段（每个域都有自己的全局范围）可用的符号，请使用方法 Symbol.for() 和 Symbol.keyFor() 从全局符号注册表中设置和检索符号。

¥The above syntax using the Symbol() function will create a Symbol whose value remains unique throughout the lifetime of the program. To create Symbols available across files and even across realms (each of which has its own global scope), use the methods Symbol.for() and Symbol.keyFor() to set and retrieve Symbols from the global Symbol registry.

请注意，"全局符号注册表" 只是一个虚构的概念，可能不对应于 JavaScript 引擎中的任何内部数据结构 - 即使存在这样的注册表，它的内容也无法用于 JavaScript 代码，除非通过 for() 和 keyFor() 方法。

¥Note that the "global Symbol registry" is only a fictitious concept and may not correspond to any internal data structure in the JavaScript engine — and even if such a registry exists, its content is not available to the JavaScript code, except through the for() and keyFor() methods.

方法 Symbol.for(tokenString) 接受一个字符串键并从注册表返回一个符号值，而 Symbol.keyFor(symbolValue) 接受一个符号值并返回与其对应的字符串键。每个都是另一个的逆，因此以下是 true：

¥The method Symbol.for(tokenString) takes a string key and returns a symbol value from the registry, while Symbol.keyFor(symbolValue) takes a symbol value and returns the string key corresponding to it. Each is the other's inverse, so the following is true:

Symbol.keyFor(Symbol.for("tokenString")) === "tokenString"; // true

因为注册符号可以在任何地方任意创建，所以它们的行为几乎与它们封装的字符串完全相同。因此，不能保证它们是唯一的并且不可垃圾回收。因此，在 WeakMap、WeakSet、WeakRef 和 FinalizationRegistry 对象中不允许使用注册符号。

¥Because registered symbols can be arbitrarily created anywhere, they behave almost exactly like the strings they wrap. Therefore, they are not guaranteed to be unique and are not garbage collectable. Therefore, registered symbols are disallowed in WeakMap, WeakSet, WeakRef, and FinalizationRegistry objects.

¥Well-known Symbols

Symbol 构造函数的所有静态属性本身都是符号，其值在各个字段中都是恒定的。它们被称为众所周知的符号，其目的是充当某些内置 JavaScript 操作的 "protocols"，允许用户自定义语言的行为。例如，如果构造函数有一个名称为 Symbol.hasInstance 的方法，则该方法将使用 instanceof 运算符对其行为进行编码。

¥All static properties of the Symbol constructor are Symbols themselves, whose values are constant across realms. They are known as well-known Symbols, and their purpose is to serve as "protocols" for certain built-in JavaScript operations, allowing users to customize the language's behavior. For example, if a constructor function has a method with Symbol.hasInstance as its name, this method will encode its behavior with the instanceof operator.

在众所周知的符号之前，JavaScript 使用普通属性来实现某些内置操作。例如，JSON.stringify 函数将尝试调用每个对象的 toJSON() 方法，而 String 函数将调用对象的 toString() 和 valueOf() 方法。然而，随着越来越多的操作被添加到语言中，将每个操作指定为 "魔法属性" 可能会破坏向后兼容性，并使语言的行为更难以推断。众所周知的符号允许自定义为正常代码的 "invisible"，通常仅读取字符串属性。

¥Prior to well-known Symbols, JavaScript used normal properties to implement certain built-in operations. For example, the JSON.stringify function will attempt to call each object's toJSON() method, and the String function will call the object's toString() and valueOf() methods. However, as more operations are added to the language, designating each operation a "magic property" can break backward compatibility and make the language's behavior harder to reason with. Well-known Symbols allow the customizations to be "invisible" from normal code, which typically only read string properties.

注意：用于使用符号 @@<symbol-name> 表示众所周知的符号的规范。例如，Symbol.hasInstance 写为 @@hasInstance，Array.prototype[Symbol.iterator]() 方法将被称为 Array.prototype[@@iterator]()。此符号不再用于规范，但你可能仍会在旧文档或讨论中看到它。

¥Note: The spec used to use the notation @@<symbol-name> to denote well-known symbols. For example, Symbol.hasInstance was written as @@hasInstance, and the Array.prototype[Symbol.iterator]() method would be called Array.prototype[@@iterator](). This notation is no longer used in the spec, but you may still see it in older documentation or discussions.

众所周知的符号没有垃圾可回收性的概念，因为它们来自固定的集合，并且在程序的整个生命周期中都是唯一的，类似于 Array.prototype 等内在对象，因此它们也允许出现在 WeakMap、WeakSet、WeakRef、 和 FinalizationRegistry 个对象。

¥Well-known symbols do not have the concept of garbage collectability, because they come in a fixed set and are unique throughout the lifetime of the program, similar to intrinsic objects such as Array.prototype, so they are also allowed in WeakMap, WeakSet, WeakRef, and FinalizationRegistry objects.

¥Finding Symbol properties on objects

方法 Object.getOwnPropertySymbols() 返回一个符号数组，并让你查找给定对象上的符号属性。请注意，每个对象都没有自己的 Symbol 属性来初始化，因此除非你在对象上设置了 Symbol 属性，否则该数组将为空。

¥The method Object.getOwnPropertySymbols() returns an array of Symbols and lets you find Symbol properties on a given object. Note that every object is initialized with no own Symbol properties, so that this array will be empty unless you've set Symbol properties on the object.

¥Constructor

Symbol()

返回 Symbol 类型的原始值。使用 new 调用时抛出错误。

¥Static properties

静态属性都是众所周知的符号。在这些符号的描述中，我们将使用诸如“Symbol.hasInstance 是一个确定...的方法”之类的语言，但请记住，这是指以该符号作为方法名称的对象方法的语义（因为众所周知的符号充当 "protocols")，没有描述符号本身的价值。

¥The static properties are all well-known Symbols. In these Symbols' descriptions, we will use language like "Symbol.hasInstance is a method determining…", but bear in mind that this is referring to the semantic of an object's method having this Symbol as the method name (because well-known Symbols act as "protocols"), not describing the value of the Symbol itself.

Symbol.asyncIterator

返回对象的默认 AsyncIterator 的方法。由 for await...of 使用。

Symbol.hasInstance

确定构造函数对象是否将对象识别为其实例的方法。由 instanceof 使用。

Symbol.isConcatSpreadable

一个布尔值，指示对象是否应展平为其数组元素。由 Array.prototype.concat() 使用。

Symbol.iterator

返回对象的默认迭代器的方法。由 for...of 使用。

Symbol.match

与字符串匹配的方法，也用于确定对象是否可以用作正则表达式。由 String.prototype.match() 使用。

Symbol.matchAll

返回迭代器的方法，该迭代器产生正则表达式与字符串的匹配。由 String.prototype.matchAll() 使用。

Symbol.replace

替换字符串的匹配子字符串的方法。由 String.prototype.replace() 使用。

Symbol.search

返回与正则表达式匹配的字符串中的索引的方法。由 String.prototype.search() 使用。

Symbol.species

用于创建派生对象的构造函数。

Symbol.split

在与正则表达式匹配的索引处分割字符串的方法。由 String.prototype.split() 使用。

Symbol.toPrimitive

将对象转换为原始值的方法。

Symbol.toStringTag

用于对象默认描述的字符串值。由 Object.prototype.toString() 使用。

Symbol.unscopables

一个对象值，其自己的和继承的属性名称被排除在关联对象的 with 环境绑定之外。

¥Static methods

Symbol.for()

使用给定的 key 在全局符号注册表中搜索现有的已注册符号，如果找到则返回。否则，将创建一个新的符号并使用 key 注册。

Symbol.keyFor()

从给定符号的全局符号注册表中检索共享符号键。

¥Instance properties

这些属性在 Symbol.prototype 上定义并由所有 Symbol 实例共享。

¥These properties are defined on Symbol.prototype and shared by all Symbol instances.

Symbol.prototype.constructor

创建实例对象的构造函数。对于 Symbol 实例，初始值为 Symbol 构造函数。

Symbol.prototype.description

包含符号描述的只读字符串。

Symbol.prototype[Symbol.toStringTag]

[Symbol.toStringTag] 属性的初始值为字符串 "Symbol"。该属性在 Object.prototype.toString() 中使用。但是，由于 Symbol 也有自己的 toString() 方法，因此除非你使用符号 thisArg 调用 Object.prototype.toString.call()，否则不会使用此属性。

¥Instance methods

Symbol.prototype.toString()

返回包含符号描述的字符串。覆盖 Object.prototype.toString() 方法。

Symbol.prototype.valueOf()

返回符号。覆盖 Object.prototype.valueOf() 方法。

Symbol.prototype[Symbol.toPrimitive]()

返回符号。

¥Examples

¥Using the typeof operator with Symbols

typeof 运算符可以帮助你识别符号。

¥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.

• 当尝试将符号转换为数字时，将抛出 TypeError（例如 +sym 或 sym | 0）。
• 当使用松散相等时，Object(sym) == sym 返回 true。
• Symbol("foo") + "bar" 抛出 TypeError （无法将 Symbol 转换为字符串）。例如，这可以防止你从符号静默创建新的字符串属性名称。
• "safer" String(sym) 转换 的工作方式类似于使用符号调用 Symbol.prototype.toString()，但请注意 new String(sym) 会抛出异常。

¥Symbols and for...in iteration

符号在 for...in 迭代中不可枚举。另外，Object.getOwnPropertyNames() 不会返回 Symbol 对象属性，但是，你可以使用 Object.getOwnPropertySymbols() 来获取这些属性。

¥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.

const obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (const i in obj) {
  console.log(i);
}
// "c" "d"

¥Symbols and JSON.stringify()

使用 JSON.stringify() 时，符号键控属性将被完全忽略：

¥Symbol-keyed properties will be completely ignored when using JSON.stringify():

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

详细信息请参见 JSON.stringify()。

¥For more details, see JSON.stringify().

¥Symbol wrapper objects as property keys

当 Symbol 封装对象用作属性键时，该对象将被强制为其封装的 Symbol：

¥When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped Symbol:

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

¥See also

• core-js 中 Symbol 的 Polyfill
• typeof
• JavaScript 数据类型和数据结构
• hacks.mozilla.org 上的 ES6 深入了解：符号 (2015)