TypeScript: 文件 - 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 視為唯一的字面量，提供了一種特殊的型別 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 (Well-known Symbols)

除了使用者定義的 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’ 環境繫結中排除的屬性名。