RegExp.prototype[Symbol.match]()

¥Syntax

regexp[Symbol.match](str)

¥Parameters

str

作为比赛目标的 String。

¥Return value

Array，其内容取决于全局 (g) 标志是否存在，或者 null（如果未找到匹配项）。

¥An Array whose contents depend on the presence or absence of the global (g) flag, or null if no matches are found.

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

¥Description

该方法在 String.prototype.match() 内部被调用。

¥This method is called internally in String.prototype.match().

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

¥For example, the following two examples return same result.

"abc".match(/a/);

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

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

¥If the regex is global (with the g flag), the regex's exec() method will be repeatedly called until exec() returns null. Otherwise, exec() would only be called once and its result becomes the return value of [Symbol.match]().

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

¥Because [Symbol.match]() would keep calling exec() until it returns null, and exec() would automatically reset the regex's lastIndex to 0 when the last match fails, [Symbol.match]() would typically not have side effects when it exits. However, when the regex is sticky but not global, lastIndex would not be reset. In this case, each call to match() may return a different result.

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 之外的任何匹配项。

¥When the regex is sticky and global, it would still perform sticky matches — i.e. it would fail to match any occurrences beyond the lastIndex.

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

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

¥If the current match is an empty string, the lastIndex would still be advanced — if the regex is Unicode-aware, it would advance by one Unicode code point; otherwise, it advances by one UTF-16 code unit.

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

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

¥This method exists for customizing match behavior within RegExp subclasses.

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

¥In addition, the [Symbol.match] property is used to check whether an object is a regular expression.

¥Examples

¥Direct call

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

¥This method can be used in almost the same way as String.prototype.match(), except the different this and the different arguments order.

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

¥Using [Symbol.match]() in subclasses

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

¥Subclasses of RegExp can override the [Symbol.match]() method to modify the default behavior.

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

¥See also

• core-js 中 RegExp.prototype[Symbol.match] 的 Polyfill
• String.prototype.match()
• RegExp.prototype[Symbol.matchAll]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype[Symbol.split]()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.match