RegExp.prototype[Symbol.match]()

基线 广泛可用

此功能已得到良好建立，并且可在许多设备和浏览器版本中使用。它已在浏览器中可用，自 2015 年 7 月.

[Symbol.match]() 方法是 RegExp 实例的方法，它指定了 String.prototype.match() 的行为方式。此外，它的存在（或不存在）会影响对象是否被视为正则表达式。

试一试

语法

js
regexp[Symbol.match](str)

参数

str

匹配目标的 String。

返回值

一个 Array，其内容取决于全局 (g) 标志的存在与否，如果未找到匹配项，则返回 null。

  • 如果使用了 g 标志，则将返回与完整正则表达式匹配的所有结果，但不包括捕获组。
  • 如果未使用 g 标志，则仅返回第一个完整匹配项及其相关的捕获组。在这种情况下，match() 将返回与 RegExp.prototype.exec() 相同的结果（一个带有一些额外属性的数组）。

描述

此方法在 String.prototype.match() 中内部调用。

例如，以下两个示例返回相同的结果。

js
"abc".match(/a/);

/a/[Symbol.match]("abc");

如果正则表达式是全局的（带有 g 标志），则正则表达式的 exec() 方法将被重复调用，直到 exec() 返回 null。否则，exec() 只会被调用一次，其结果将成为 [Symbol.match]() 的返回值。

因为 [Symbol.match]() 会一直调用 exec() 直到它返回 null，并且 exec() 会在最后一次匹配失败时自动将正则表达式的 lastIndex 重置为 0，所以 [Symbol.match]() 在退出时通常不会产生副作用。但是，当正则表达式是 粘性的 但不是全局的时，lastIndex 不会被重置。在这种情况下，每次调用 match() 可能会返回不同的结果。

js
const re = /[abc]/y;
for (let i = 0; i < 5; i++) {
  console.log("abc".match(re), re.lastIndex);
}
// [ 'a' ] 1
// [ 'b' ] 2
// [ 'c' ] 3
// null 0
// [ 'a' ] 1

当正则表达式是粘性和全局的时，它仍然会执行粘性匹配——即，它将无法匹配 lastIndex 之后的任何出现。

js
console.log("ab-c".match(/[abc]/gy)); // [ 'a', 'b' ]

如果当前匹配项是空字符串，则 lastIndex 仍将前进——如果正则表达式是 Unicode 感知 的，它将前进一个 Unicode 代码点；否则，它将前进一个 UTF-16 代码单元。

js
console.log("😄".match(/(?:)/g)); // [ '', '', '' ]
console.log("😄".match(/(?:)/gu)); // [ '', '' ]

此方法用于在 RegExp 子类中自定义匹配行为。

此外，[Symbol.match] 属性用于检查 对象是否为正则表达式。

示例

直接调用

此方法的使用方式与 String.prototype.match() 几乎相同，只是 this 和参数顺序不同。

js
const re = /[0-9]+/g;
const str = "2016-01-02";
const result = re[Symbol.match](str);
console.log(result); // ["2016", "01", "02"]

在子类中使用 [Symbol.match]()

RegExp 的子类可以重写 [Symbol.match]() 方法以修改默认行为。

js
class MyRegExp extends RegExp {
  [Symbol.match](str) {
    const result = RegExp.prototype[Symbol.match].call(this, str);
    if (!result) return null;
    return {
      group(n) {
        return result[n];
      },
    };
  }
}

const re = new MyRegExp("([0-9]+)-([0-9]+)-([0-9]+)");
const str = "2016-01-02";
const result = str.match(re); // String.prototype.match calls re[Symbol.match]().
console.log(result.group(1)); // 2016
console.log(result.group(2)); // 01
console.log(result.group(3)); // 02

规范

规范
ECMAScript 语言规范
# sec-regexp.prototype-%symbol.match%

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅