Symbols - TypeScript 中文文档

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

通过调用 Symbol 构造函数可以创建 symbol 值。

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

Symbol 值不可变且唯一。

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

与字符串一样，symbol 也可以用作对象属性的键。

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

symbol 还可以与计算属性声明结合使用，以声明对象属性和类成员。

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

`unique symbol`

为了能够将 symbol 视为唯一的字面量，TypeScript 提供了特殊类型 unique symbol。unique symbol 是 symbol 的子类型，只能通过调用 Symbol() 或 Symbol.for()，或者通过显式的类型注解来产生。此类型只允许用在 const 声明和 readonly static 属性上，并且要引用某个特定的唯一 symbol，必须使用 typeof 运算符。每个对唯一 symbol 的引用都意味着一个与给定声明绑定的完全唯一的标识。

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 类型之间都不可以相互赋值或比较。

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

众所周知的 Symbol

除了用户定义的 symbol 之外，还有一些众所周知的內置 symbol。內置 symbol 用于表示语言的内部行为。

下面是众所周知的 symbol 列表：

`Symbol.asyncIterator`

一个方法，返回对象的异步迭代器，可与 for await..of 循环配合使用。

`Symbol.hasInstance`

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

`Symbol.isConcatSpreadable`

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

`Symbol.iterator`

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

`Symbol.match`

一个正则表达式方法，用于将正则表达式与字符串进行匹配。由 String.prototype.match 方法调用。

`Symbol.replace`

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

`Symbol.search`

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

`Symbol.species`

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

`Symbol.split`

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

`Symbol.toPrimitive`

一个方法，用于将对象转换为对应的原始值。由 ToPrimitive 抽象操作调用。

`Symbol.toStringTag`

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

`Symbol.unscopables`

一个对象，其自身属性名会被排除在关联对象的 “with” 环境绑定之外。