Symbol.match 是 JavaScript 中用于自定义对象在 String.prototype.match() 中行为的内置 symbol，需实现为接收字符串并返回匹配数组或 null 的方法，支持模拟 RegExp 的 flags 行为。
Symbol.match 是 JavaScript 中一个内置的 symbol，用于自定义对象在被 String.prototype.match() 方法调用时的行为。它本质上是一个方法属性，当正则表达式（或类似正则的对象）被传入 match() 时，引擎会检查该对象是否具有 [Symbol.match] 方法，并优先调用它，而不是默认执行正则匹配逻辑。
让非正则对象支持 match() 调用
通常只有 RegExp 实例能被 str.match(reg) 正常处理。但如果你有一个自定义类（比如一个“模糊匹配器”或“关键词提取器”），想让它也能直接参与 match() 调用，就可以实现 [Symbol.match]。
- 该方法接收一个字符串参数（即调用
match()时传入的目标字符串） - 返回值应与原生
RegExp.prototype[Symbol.match]一致：匹配成功返回数组（含捕获组）、null表示无匹配 - 注意：返回值不会被自动包装成
Array；必须是数组或null
基本用法示例
下面是一个简单但完整的例子，定义一个只匹配“hello”的自定义匹配器：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
class HelloMatcher {
[Symbol.match](str) {
const index = str.indexOf('hello');
if (index !== -1) {
return ['hello']; // 模拟匹配结果
}
return null;
}
}
const matcher = new HelloMatcher();
console.log('say hello world'.match(matcher)); // ['hello']
console.log('hi there'.match(matcher)); // null
与 RegExp 的行为保持一致
如果你想让自定义对象表现得像真正的正则，还需注意全局标志 g、忽略大小写 i 等行为。虽然 [Symbol.match] 不强制你解析 flags，但若要兼容性好，建议读取对象自身的 flags 属性并响应相应逻辑：
立即学习“Java免费学习笔记（深入）”；
- 如果对象有
global属性为true，应返回所有匹配项组成的数组（而非仅第一个） - 如果有
ignoreCase，需做大小写不敏感判断 - 原生 RegExp 的
match()在g模式下返回纯匹配数组（不含额外信息），无g时返回带index、input等属性的数组 —— 自定义实现可按需模拟
常见误区提醒
使用 Symbol.match 时容易忽略几个关键点：
- 不能直接在普通对象字面量上设置：
{ [Symbol.match]: fn }可以，但该对象不是RegExp，也不会被instanceof RegExp判定为真 -
String.prototype.match只会在参数“看起来像正则”时触发该 symbol —— 即参数有[Symbol.match]方法，不管它是不是 RegExp 实例 - 如果对象同时有
[Symbol.match]和exec方法，match()仍只调用[Symbol.match]，不会 fallback 到exec - 浏览器和 Node.js 均支持，无需 polyfill（ES2015+）
