CKTIS / JavaScript
String.prototype.matchAll — Iterator für Treffer mit Erfassungsgruppen
String.prototype.matchAll liefert einen Iterator über Treffer eines regulären Ausdrucks, einschließlich Erfassungsgruppen und Positionen. Bei einem gewöhnlichen RegExp ist das Flag g erforderlich; lastIndex des ursprünglichen Musters bleibt unverändert.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
string.matchAll(regexp)Mit String.prototype.matchAll kannst du Text nach Treffern eines Musters durchsuchen. Bei standardmäßigem RegExp-Verhalten liefert die Methode einen verzögerten Iterator: Jeder Schritt ergibt ein Array, dessen [0] den vollständigen Treffer und dessen [1], [2] usw. die Erfassungsgruppen enthalten. Eine nicht passende optionale Gruppe hat den Wert undefined. Die Eigenschaft index gibt die Position in UTF-16-Codeeinheiten an, input enthält den Eingabetext und groups stellt vorhandene benannte Gruppen bereit.
Wenn das Argument als regulärer Ausdruck erkannt wird, prüft matchAll das Flag g, bevor es nach Symbol.matchAll sucht. Fehlt das Flag, löst der Aufruf einen TypeError aus. Die Suche berücksichtigt auch geerbte Eigenschaften: Ist der gefundene Wert aufrufbar, ruft matchAll ihn auf und gibt sein Ergebnis zurück. Fehlt die Eigenschaft oder ist ihr Wert undefined oder null, erzeugt matchAll aus dem Argument ein RegExp mit dem Flag g. In diesem Fall wird eine Zeichenfolge als Suchmuster für einen regulären Ausdruck behandelt, nicht als wörtlicher Text. Jeder andere nicht aufrufbare Wert von Symbol.matchAll löst einen TypeError aus.
Die standardmäßige RegExp-Implementierung erstellt eine Kopie des Musters und setzt deren anfänglichen lastIndex auf das Ergebnis von ToLength für den lastIndex des Originals. So wird aus -1 beispielsweise 0 und aus 2.9 wird 2. Der lastIndex des Originals bleibt unverändert. Gehe daher nicht davon aus, dass die Suche immer bei null beginnt. Der Iterator kann nur einmal verwendet werden: Ist er erschöpft, beginnt er nicht erneut. Keine Treffer bedeuten eine leere Iteration, nicht null; verwende for...of, um Ergebnisse zu verarbeiten, oder [...iterator], um sie in einem Array zu speichern.
Anders als match mit dem Flag g behält matchAll die Erfassungsgruppen für jeden Treffer bei. Die Methode gehört zu ECMAScript 2020, nicht zu den Web APIs. Die Spezifikation allein belegt keine Unterstützung in einem bestimmten Browser; auch Node 24 in einem Repository ist dafür kein Beweis. Die Verfügbarkeit in der Zielumgebung lässt sich mit typeof String.prototype.matchAll === "function" prüfen.
Beispiele
const text = "x=12 y=7";
const pattern = /([a-z])=(\d+)/g;
const matches = text.matchAll(pattern);
for (const match of matches) {
console.log(`${match[0]} | ${match[1]} | ${match[2]} | ${match.index}`);
}
console.log(`lastIndex=${pattern.lastIndex}`);
console.log(`remaining=${[...matches].length}`);Ergebnis
x=12 | x | 12 | 0 y=7 | y | 7 | 5 lastIndex=0 remaining=0
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.