符号

从 ECMAScript 2015 开始，symbol 是原始数据类型，就像 number 和 string 一样。

¥Starting with ECMAScript 2015, symbol is a primitive data type, just like number and string.

symbol 值是通过调用 Symbol 构造函数创建的。

¥symbol values are created by calling the Symbol constructor.

ts
let sym1 = Symbol();
let sym2 = Symbol("key"); // optional string key

符号是不可变的，并且是唯一的。

¥Symbols are immutable, and unique.

ts
let sym2 = Symbol("key");
let sym3 = Symbol("key");
sym2 === sym3; // false, symbols are unique

就像字符串一样，符号可以用作对象属性的键。

¥Just like strings, symbols can be used as keys for object properties.

ts
const sym = Symbol();
let obj = {
  [sym]: "value",
};
console.log(obj[sym]); // "value"

符号也可以与计算属性声明相结合来声明对象属性和类成员。

¥Symbols can also be combined with computed property declarations to declare object properties and class members.

ts
const getClassNameSymbol = Symbol();
class C {
  [getClassNameSymbol]() {
    return "C";
  }
}
let c = new C();
let className = c[getClassNameSymbol](); // "C"

unique symbol

为了能够将符号视为唯一字面，可以使用特殊类型 unique symbol。unique symbol 是 symbol 的子类型，仅通过调用 Symbol() 或 Symbol.for() 或显式类型注释产生。这种类型只允许在 const 声明和 readonly static 属性上使用，为了引用特定的唯一符号，你必须使用 typeof 运算符。每个对唯一符号的引用都意味着与给定声明相关联的完全唯一标识。

¥To enable treating symbols as unique literals a special type unique symbol is available. unique symbol is a subtype of symbol, and are produced only from calling Symbol() or Symbol.for(), or from explicit type annotations. This type is only allowed on const declarations and readonly static properties, and in order to reference a specific unique symbol, you’ll have to use the typeof operator. Each reference to a unique symbol implies a completely unique identity that’s tied to a given declaration.

ts
declare const sym1: unique symbol;
 
// sym2 can only be a constant reference.
let sym2: unique symbol = Symbol();
A variable whose type is a 'unique symbol' type must be 'const'.1332A variable whose type is a 'unique symbol' type must be 'const'.
 
// Works - refers to a unique symbol, but its identity is tied to 'sym1'.
let sym3: typeof sym1 = sym1;
 
// Also works.
class C {
  static readonly StaticSymbol: unique symbol = Symbol();
}Try

因为每个 unique symbol 都有一个完全独立的标识，所以没有两个 unique symbol 类型可以分配或相互比较。

¥Because each unique symbol has a completely separate identity, no two unique symbol types are assignable or comparable to each other.

ts
const sym2 = Symbol();
const sym3 = Symbol();
 
if (sym2 === sym3) {
This comparison appears to be unintentional because the types 'typeof sym2' and 'typeof sym3' have no overlap.2367This comparison appears to be unintentional because the types 'typeof sym2' and 'typeof sym3' have no overlap.
  // ...
}Try

知名符号

¥Well-known Symbols

除了用户定义的符号外，还有众所周知的内置符号。内置符号用于表示内部语言行为。

¥In addition to user-defined symbols, there are well-known built-in symbols. Built-in symbols are used to represent internal language behaviors.

以下是知名符号的列表：

¥Here is a list of well-known symbols:

Symbol.asyncIterator

返回对象的异步迭代器的方法，与 for await..of 循环兼容。

¥A method that returns async iterator for an object, compatible to be used with for await..of loop.

Symbol.hasInstance

一种确定构造函数对象是否将对象识别为构造函数实例之一的方法。由 instanceof 运算符的语义调用。

¥A method that determines if a constructor object recognizes an object as one of the constructor’s instances. Called by the semantics of the instanceof operator.

Symbol.isConcatSpreadable

一个布尔值，指示对象应通过 Array.prototype.concat 展平为其数组元素。

¥A Boolean value indicating that an object should be flattened to its array elements by Array.prototype.concat.

Symbol.iterator

返回对象的默认迭代器的方法。由 for-of 语句的语义调用。

¥A method that returns the default iterator for an object. Called by the semantics of the for-of statement.

Symbol.match

将正则表达式与字符串匹配的正则表达式方法。由 String.prototype.match 方法调用。

¥A regular expression method that matches the regular expression against a string. Called by the String.prototype.match method.

Symbol.replace

替换字符串的匹配子字符串的正则表达式方法。由 String.prototype.replace 方法调用。

¥A regular expression method that replaces matched substrings of a string. Called by the String.prototype.replace method.

Symbol.search

一种正则表达式方法，它返回与正则表达式匹配的字符串中的索引。由 String.prototype.search 方法调用。

¥A regular expression method that returns the index within a string that matches the regular expression. Called by the String.prototype.search method.

Symbol.species

一个函数值属性，它是用于创建派生对象的构造函数。

¥A function valued property that is the constructor function that is used to create derived objects.

Symbol.split

一种在与正则表达式匹配的索引处拆分字符串的正则表达式方法。由 String.prototype.split 方法调用。

¥A regular expression method that splits a string at the indices that match the regular expression. Called by the String.prototype.split method.

Symbol.toPrimitive

一种将对象转换为相应基础值的方法。由 ToPrimitive 抽象操作调用。

¥A method that converts an object to a corresponding primitive value. Called by the ToPrimitive abstract operation.

Symbol.toStringTag

一个字符串值，用于创建对象的默认字符串描述。由内置方法 Object.prototype.toString 调用。

¥A String value that is used in the creation of the default string description of an object. Called by the built-in method Object.prototype.toString.

Symbol.unscopables

一个对象，其自身的属性名称是从关联对象的 ‘with’ 环境绑定中排除的属性名称。

¥An Object whose own property names are property names that are excluded from the ‘with’ environment bindings of the associated objects.