Erfassungsgruppe: (...) — Keyword · JavaScript-Referenz

Signatur

(pattern)

Beschreibung

Eine Erfassungsgruppe (englisch: capturing group) fasst ein Teilmuster eines regulären Ausdrucks in runde Klammern zusammen. Damit können Sie einen Quantor auf die ganze Gruppe anwenden, zum Beispiel (ab)+, oder eine Disjunktion eingrenzen, zum Beispiel (Herr|Frau) Meier. Außerdem merkt sich die Engine den Text, auf den die Gruppe gepasst hat.

Die Gruppen werden von links nach rechts nach der Position ihrer öffnenden Klammer durchnummeriert, beginnend bei 1. Auf den erfassten Text greifen Sie so zu:

im Ergebnis-Array von RegExp.prototype.exec(), String.prototype.match() (ohne g-Flag) oder String.prototype.matchAll() über die Indizes [1], [2] usw.,
in der Ersetzungszeichenkette von String.prototype.replace() über $1, $2 usw. bzw. als Argumente einer Ersetzungsfunktion,
innerhalb desselben Musters über eine Rückreferenz wie \1.

Wenn Sie nur gruppieren und nichts erfassen wollen, verwenden Sie die nicht erfassende Gruppe (?:...). Das hält die Nummerierung übersichtlich und ist etwas schneller. Bei vielen Gruppen empfehlen sich benannte Erfassungsgruppen (?<name>...), weil Sie dann über match.groups.name zugreifen können, statt Positionen zu zählen.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	RegExp-Teilmuster		Beliebiges Teilmuster, auch mit Alternativen (`\|`), Quantoren oder weiteren, verschachtelten Gruppen. Der Text, auf den es passt, wird erfasst.

Rückgabewert

Typ

string | undefined

Beschreibung

Der erfasste Teiltext steht im Ergebnis-Array an der Position der Gruppennummer. Hat die Gruppe nicht am Treffer teilgenommen (etwa in einem nicht gewählten Zweig von |), steht dort undefined.

Beispiele

Datum in Bestandteile zerlegen

const match = /(\d{4})-(\d{2})-(\d{2})/.exec("Lieferung am 2024-03-15");
const [, jahr, monat, tag] = match;
console.log(jahr, monat, tag);
console.log(match.index);

2024 03 15 13

Reihenfolge per $1/$2 umstellen

const name = "Müller, Hans";
console.log(name.replace(/([^,]+),\s*(.+)/, "$2 $1"));

// Mit Ersetzungsfunktion
const preis = "Preis: 12.50 EUR".replace(/(\d+)\.(\d{2})/, (_, euro, cent) => `${euro},${cent}`);
console.log(preis);

Hans Müller Preis: 12,50 EUR

Quantor auf Gruppe: nur letzte Wiederholung wird erfasst

const m = /(ab)+/.exec("xxababab");
console.log(m[0], m[1]);

ababab ab

Alle Treffer mit Gruppen via matchAll

const log = "user=anna id=7; user=ben id=12";
for (const [, user, id] of log.matchAll(/user=(\w+) id=(\d+)/g)) {
  console.log(`${user} → ${Number(id)}`);
}

anna → 7 ben → 12

Rückreferenz: passende Anführungszeichen

const re = /(["'])(.*?)\1/;
console.log(re.exec(`Er sagte 'Hallo' und ging.`)[2]);
console.log(re.test(`"gemischt'`));

Hallo false

split() übernimmt erfasste Trenner

console.log("a1b2c".split(/(\d)/));
console.log("a1b2c".split(/(?:\d)/));

[ 'a', '1', 'b', '2', 'c' ] [ 'a', 'b', 'c' ]

// Wichtig · Fallstricke

match() mit g-Flag gibt nur die Gesamttreffer zurück, keine Gruppen. Verwenden Sie dafür matchAll() oder exec() in einer Schleife.
Wiederholte Gruppen wie (\d)+ erfassen nur die letzte Wiederholung. Wenn Sie alle Werte brauchen, erfassen Sie den ganzen Bereich (\d+) und zerlegen ihn danach.
Nicht beteiligte Gruppen liefern undefined. In replace() wird $n dann zur leeren Zeichenkette.
Nummerierung: Es zählt die Reihenfolge der öffnenden Klammern, auch bei verschachtelten Gruppen. (?:...), Lookarounds und andere (?...)-Konstrukte werden nicht mitgezählt, benannte Gruppen dagegen schon.
Mehrdeutigkeit bei $10: Gibt es weniger als zehn Gruppen, wird $10 als $1 gefolgt von 0 gelesen.
split() fügt erfasste Gruppen ins Ergebnis-Array ein. Verwenden Sie (?:...), wenn Sie das nicht wollen.
Positionen: Mit dem Flag d (ES2022) liefert match.indices Start- und Endposition jeder Gruppe.
Leistung/ReDoS: Verschachtelte Quantoren wie (a+)+ können bei ungeeigneten Eingaben katastrophales Backtracking auslösen. Das ist bei Nutzereingaben ein Sicherheitsrisiko.

Siehe auch

RegExp.prototype.exec() String.prototype.replace() Benannte Erfassungsgruppe: (?<name>...) Disjunction: | Nicht speichernde Gruppe: (?:...)