原始类型Symbol 符号

Symbol 符号

js/symbol2026-10-29 11:03:47

Symbol 是具有唯一性并且不可变的原始类型。在某些程序语言当中，Symbol 也被称作“原子（atom）类型”。

Symbol 的唯一性

每个从 Symbol() 返回的 Symbol 值都是 唯一的。

Symbol 类型的主要用途是为对象属性提供 唯一的 标识符，以避免属性名冲突，在 JavaScript 内部机制中有广泛的应用，这是该数据类型仅有的目的。

创建 Symbol

创建 Symbol 值

直接使用 Symbol() 创建新的 symbol 类型值，并用一个可选的字符串作为其描述。

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

上面的代码创建了三个新的 symbol 类型值。注意，Symbol("foo") 不会强制将字符串 "foo" 转换成 symbol 类型值。

唯一性

Symbol() 每次都会创建一个新的 symbol 类型值，即使它们有相同的描述。

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

创建 Symbol 包装器对象

使用 new 运算符调用 Symbol() 将抛出 TypeError 错误：

var sym = new Symbol(); // TypeError

这会阻止创建一个显式的 Symbol 包装器对象而不是一个 Symbol 值。

围绕原始数据类型创建一个显式包装器对象从 ECMAScript 6 开始不再被支持。然而，现有的原始包装器对象，如 new Boolean、new String 以及 new Number，因为遗留原因仍可被创建。

如果你真的想创建一个 Symbol 包装器对象 (Symbol wrapper object)，你可以使用 Object() 函数：

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

全局共享的 Symbol

上面使用 Symbol() 函数的语法，不会在你的整个代码库中创建一个可用的全局的 symbol 类型值。要创建跨文件可用的 symbol，甚至跨域（每个都有它自己的全局作用域），使用 Symbol.for() 方法和 Symbol.keyFor() 方法从 全局的 symbol 注册表 设置和取得 symbol。

对象中的 Symbol 属性

在对象中查找 Symbol 属性

Object.getOwnPropertySymbols() 方法让你在查找一个给定对象的符号属性时返回一个 symbol 类型的数组。注意，每个初始化的对象都是没有自己的 symbol 属性的，因此这个数组可能为空，除非你已经在对象上设置了 symbol 属性。

Symbols 与 for...in 迭代

Symbols 在 for...in 迭代中不可枚举。另外，Object.getOwnPropertyNames() 不会返回 symbol 对象的属性，但是你能使用 Object.getOwnPropertySymbols() 得到它们。

var obj = {};

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

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

Symbols 与 JSON.stringify()

当使用 JSON.stringify() 时，以 symbol 值作为键的属性会被完全忽略：

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

Symbol 包装器对象作为属性的键

当一个 Symbol 包装器对象作为一个属性的键时，这个对象将被强制转换为它包装过的 symbol 值：

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

内置的 Symbol 值

JavaScript 还提供了一些内置的 Symbol 值，用于语言内部的行为。

迭代 symbols

  • Symbol.iterator：用于定义对象的默认迭代器。
  • Symbol.asyncIterator：用于定义对象的默认异步迭代器。

正则表达式 symbols

  • Symbol.match：用于配置对象是否可以作为 String.prototype.match() 方法的参数。
  • Symbol.replace：用于配置对象是否可以作为 String.prototype.replace() 方法的参数。
  • Symbol.search：用于配置对象是否可以作为 String.prototype.search() 方法的参数。
  • Symbol.split：用于配置对象是否可以作为 String.prototype.split() 方法的参数。

其他 symbols

  • Symbol.hasInstance：用于判断对象是否是某个构造函数的实例。
  • Symbol.isConcatSpreadable：用于配置对象在数组的 concat() 方法中是否展开。
  • Symbol.toPrimitive：用于配置对象在转换为原始值时的行为。
  • Symbol.toStringTag：用于配置对象的默认字符串描述。
  • Symbol.unscopables：用于配置对象的属性在 with 语句中是否被排除。
  • Symbol.species：用于创建派生对象的构造器函数。

Symbol 类型转换

typeof 运算符能帮助你识别 symbol 类型：

typeof Symbol() === "symbol";
typeof Symbol("foo") === "symbol";
typeof Symbol.iterator === "symbol";

当使用 symbol 值进行类型转换时需要注意一些事情：

  • 尝试将一个 symbol 值转换为一个 number 值时，会抛出一个 TypeError 错误 (e.g. +sym or sym | 0).
  • 使用宽松相等时，Object(sym) == sym 返回 true.
  • 不允许从一个 symbol 值隐式地创建一个新的 string 类型的属性名。例如，Symbol("foo") + "bar" 将抛出一个 TypeError (can't convert symbol to string).
  • 字符串强制转换 String(sym) 的作用会像 symbol 类型调用 Symbol.prototype.toString() 一样，但是注意 new String(sym) 将抛出异常。

参考

JavaScript 数据类型和数据结构
https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Data_structures

Symbol 对象
https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Symbol

本页目录