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 July 2015.

Die [Symbol.matchAll]()-Methode von RegExp-Instanzen gibt vor, wie String.prototype.matchAll funktionieren soll.

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("-[0-9]+", "g");
console.log("2016-01-02|2019-03-07".matchAll(re));
// Expected output: Array [Array ["-01"], Array ["-02"], Array ["-03"], Array ["-07"]]

Syntax

js
regexp[Symbol.matchAll](str)

Parameter

str

Ein String, der das Ziel des Abgleichs ist.

Rückgabewert

Ein iterierbares Iterator-Objekt (das nicht erneut gestartet werden kann) für die Übereinstimmungen. Jede Übereinstimmung ist ein Array mit der gleichen Struktur wie der Rückgabewert von RegExp.prototype.exec().

Beschreibung

Diese Methode wird intern in String.prototype.matchAll() aufgerufen. Zum Beispiel führen die folgenden zwei Beispiele zum gleichen Ergebnis.

js
"abc".matchAll(/a/g);

/a/g[Symbol.matchAll]("abc");

Ähnlich wie [Symbol.split]() verwendet [Symbol.matchAll]() zuerst [Symbol.species], um ein neues Regex zu erstellen, wodurch die ursprüngliche Regex in keiner Weise verändert wird. Der lastIndex beginnt mit dem Wert des ursprünglichen Regex.

js
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 die Eingabe ein globales Regex ist, erfolgt in String.prototype.matchAll(). [Symbol.matchAll]() überprüft die Eingabe nicht. Wenn das Regex nicht global ist, liefert der zurückgegebene Iterator einmal das Ergebnis von exec() und gibt dann undefined zurück. Wenn das Regex global ist, wird jedes Mal, wenn die next()-Methode des zurückgegebenen Iterators aufgerufen wird, das exec() auf das Regex aufgerufen und das Ergebnis erzeugt.

Wenn das Regex sticky und global ist, führt es weiterhin sticky-Abgleiche durch — d. h., es werden keine Vorkommen über den lastIndex hinaus abgeglichen.

js
console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]

Wenn die aktuelle Übereinstimmung ein leerer String ist, wird der lastIndex dennoch weitergeschaltet. Wenn das Regex das u-Flag hat, wird es um einen Unicode-Codepoint weitergeschaltet; andernfalls um einen UTF-16-Codepoint.

js
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 fast genauso verwendet werden wie String.prototype.matchAll(), abgesehen von dem unterschiedlichen Wert von this und der unterschiedlichen Reihenfolge der Argumente.

js
const re = /[0-9]+/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:

js
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("([0-9]+)-([0-9]+)-([0-9]+)", "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® 2025 Language Specification
# sec-regexp-prototype-%symbol.matchall%

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.matchAll]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch