WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Benannte RegExp-Gruppen und Platzhalter im Ersetzungstext

Lies erfassten Text anhand des Gruppennamens aus und setze ihn mit einer Ersetzungszeichenfolge oder einer Rückruffunktion wieder ein.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

/(?<name>pattern)/
/(?<name>pattern)\k<name>/
regexp.exec(text)?.groups?.name
text.replace(regexp, "$<name>")
text.replace(regexp, replacer)
text.replaceAll(globalRegexp, replacement)
Replacement string tokens: $$, $&, $`, $', $1 … $99, $<name>

(?<name>...) erfasst den Text, auf den ein Teilmuster passt. Benannte und unbenannte Gruppen werden gemeinsam ab 1 nach der Reihenfolge ihrer öffnenden Klammern nummeriert; (?:...) erfasst nichts. Nach einem erfolgreichen exec() liefert result.groups.name den Wert; hat die Gruppe nicht zum Treffer beigetragen, ist der Wert undefined. \k<name> ist eine Rückreferenz im Muster, die den erfassten Text abgleicht, statt ihn in das Ersetzungsergebnis einzufügen.

In einer Ersetzungszeichenfolge setzt $<name> die benannte Gruppe ein, $1 die erste Gruppe, $& den gesamten Treffer und $$ ein Dollarzeichen. $` und $' setzen den ursprünglichen Text vor beziehungsweise nach dem Treffer ein. Hat das Muster benannte Gruppen, ergibt ein unbekannter Name oder eine nicht beteiligte Gruppe eine leere Zeichenfolge. Ohne benannte Gruppen bleibt $<name> wörtlich erhalten. Eine vorhandene, aber nicht beteiligte nummerierte Gruppe ergibt ebenfalls eine leere Zeichenfolge. Fehlt Gruppe 12, kann $12 für $1 gefolgt von einer wörtlichen 2 stehen, sofern Gruppe 1 existiert.

Die Ersetzungsfunktion erhält den gesamten Treffer, die Gruppenwerte der Reihe nach, den Offset in UTF-16-Codeeinheiten, die Eingabezeichenfolge und zuletzt ein groups-Objekt, falls das Muster benannte Gruppen enthält. Nicht beteiligte Gruppen haben den Wert undefined. Der Rückgabewert wird nicht als Ersetzungsvorlage ausgewertet: () => text fügt Text mit $ wörtlich ein.

Mit einem gewöhnlichen RegExp ersetzt replace() ohne die Flags g und y nur den ersten Treffer, mit g ohne y dagegen alle Treffer. Mit y ohne g ersetzt die Methode höchstens einen Treffer, der beim aktuellen lastIndex beginnen muss. Mit gy beginnt sie an Position 0 und bricht ab, sobald an der aktuellen Position kein Treffer vorliegt, ohne weiterzusuchen. replaceAll() wirft bei einem regulären Ausdruck ohne g einen TypeError. Beide Methoden geben eine Ergebniszeichenfolge zurück, ohne die Eingabe zu verändern.

Gruppennamen folgen der Bezeichnersyntax. Ein ungültiger Name führt zu einem SyntaxError; in ECMAScript 2024 gilt das auch für jeden doppelten Namen. ECMAScript 2025 erlaubt denselben Namen in getrennten Zweigen derselben |-Alternative. Prüfe die Unterstützung in der Ziellaufzeit und verwende für ECMAScript-2024-Kompatibilität eindeutige Namen.

Beispiele

const text = "AB-12 CD";
const token = /(?<code>[A-Z]{2})(?:-(?<number>\d+))?/g;

console.log(text.replace(token, "[$<code>:$<number>]"));
console.log(text.replace(token, (match, code, number, offset, input, groups) =>
  `[${groups.code}:${groups.number ?? "none"}]`
));

Ergebnis

[AB:12] [CD:]
[AB:12] [CD:none]

Bei `CD` trägt die Gruppe `number` nicht zum Treffer bei. Die Ersetzungszeichenfolge lässt das Feld leer, die Rückruffunktion setzt `none` ein.

Zugehörige Lektionen

  • JavaScript · Lektion 25 · Mittlere Stufe · Version: 3

Quellen