RegExp.prototype[Symbol.matchAll]()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Die [Symbol.matchAll]()
-Methode von RegExp
-Instanzen spezifiziert, wie String.prototype.matchAll
funktionieren sollte.
Probieren Sie es aus
class MyRegExp extends RegExp {
[Symbol.matchAll](str) {
const result = RegExp.prototype[Symbol.matchAll].call(this, str);
if (!result) {
return null;
}
return Array.from(result);
}
}
const re = new MyRegExp("-\\d+", "g");
console.log("2016-01-02|2019-03-07".matchAll(re));
// Expected output: Array [Array ["-01"], Array ["-02"], Array ["-03"], Array ["-07"]]
Syntax
regexp[Symbol.matchAll](str)
Parameter
Rückgabewert
Ein iterierbares Iterator-Objekt (welches nicht wieder startbar ist) der Übereinstimmungen. Jede Übereinstimmung ist ein Array mit derselben Struktur wie der Rückgabewert von RegExp.prototype.exec()
.
Beschreibung
Diese Methode wird intern in String.prototype.matchAll()
aufgerufen. Zum Beispiel ergeben die folgenden beiden Beispiele dasselbe Resultat.
"abc".matchAll(/a/g);
/a/g[Symbol.matchAll]("abc");
Ähnlich wie [Symbol.split]()
beginnt [Symbol.matchAll]()
mit der Verwendung von [Symbol.species]
, um ein neues Regex zu erstellen, wodurch eine Änderung des ursprünglichen Regex vermieden wird. lastIndex
beginnt mit dem Wert des ursprünglichen Regex.
const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
// [ "1 b", "1 c" ]
Die Überprüfung, ob der Input ein globaler Regex ist, erfolgt in String.prototype.matchAll()
. [Symbol.matchAll]()
validiert den Input nicht. Ist das Regex nicht global, liefert der zurückgegebene Iterator das exec()
-Ergebnis einmal und gibt dann undefined
zurück. Ist das Regex global, wird jedes Mal, wenn die next()
-Methode des zurückgegebenen Iterators aufgerufen wird, das exec()
des Regex aufgerufen und das Ergebnis ausgegeben.
Wenn das Regex sticky und global ist, werden dennoch Sticky Matches durchgeführt – d.h. es werden keine Vorkommen jenseits des lastIndex
erfasst.
console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]
Wenn die aktuelle Übereinstimmung ein leerer String ist, wird der lastIndex
dennoch weitergeführt. Hat das Regex das Flag u
, wird um einen Unicode-Codepoint erhöht; andernfalls um einen UTF-16-Codepoint.
console.log(Array.from("😄".matchAll(/(?:)/g)));
// [ [ "" ], [ "" ], [ "" ] ]
console.log(Array.from("😄".matchAll(/(?:)/gu)));
// [ [ "" ], [ "" ] ]
Diese Methode existiert, um das Verhalten von matchAll()
in RegExp
-Unterklassen anzupassen.
Beispiele
Direkter Aufruf
Diese Methode kann auf fast die gleiche Weise wie String.prototype.matchAll()
verwendet werden, abgesehen von den unterschiedlichen Werten von this
und der unterschiedlichen Reihenfolge der Argumente.
const re = /\d+/g;
const str = "2016-01-02";
const result = re[Symbol.matchAll](str);
console.log(Array.from(result, (x) => x[0]));
// [ "2016", "01", "02" ]
Verwendung von [Symbol.matchAll]()
in Unterklassen
Unterklassen von RegExp
können die [Symbol.matchAll]()
-Methode überschreiben, um das Standardverhalten zu ändern.
Zum Beispiel, um ein Array
anstelle eines Iterators zurückzugeben:
class MyRegExp extends RegExp {
[Symbol.matchAll](str) {
const result = RegExp.prototype[Symbol.matchAll].call(this, str);
return result ? Array.from(result) : null;
}
}
const re = new MyRegExp("(\\d+)-(\\d+)-(\\d+)", "g");
const str = "2016-01-02|2019-03-07";
const result = str.matchAll(re);
console.log(result[0]);
// [ "2016-01-02", "2016", "01", "02" ]
console.log(result[1]);
// [ "2019-03-07", "2019", "03", "07" ]
Spezifikationen
Specification |
---|
ECMAScript® 2026 Language Specification # sec-regexp-prototype-%symbol.matchall% |