String.prototype.replace() — Methode · JavaScript-Referenz

Signatur

replace(pattern, replacement)

Beschreibung

Die Methode replace() von String-Werten gibt einen neuen String zurück, in dem eines, mehrere oder alle Übereinstimmungen eines pattern durch ein replacement ersetzt werden. Das pattern kann ein String oder eine RegExp sein, und das replacement kann ein String oder eine Funktion sein, die für jede Übereinstimmung aufgerufen wird. Wenn pattern ein String ist, wird nur das erste Vorkommen ersetzt. Der ursprüngliche String bleibt unverändert.

Diese Methode verändert den String-Wert, auf dem sie aufgerufen wird, nicht. Sie gibt einen neuen String zurück.

Ein String-Pattern wird nur einmal ersetzt. Um eine globale Suche und Ersetzung durchzuführen, verwenden Sie einen regulären Ausdruck mit dem g-Flag oder verwenden Sie stattdessen replaceAll().

Wenn pattern ein Objekt mit einer Symbol.replace-Methode ist (einschließlich RegExp-Objekten), wird diese Methode mit dem Ziel-String und replacement als Argumenten aufgerufen. Ihr Rückgabewert wird zum Rückgabewert von replace(). In diesem Fall wird das Verhalten von replace() vollständig durch die [Symbol.replace]()-Methode kodiert – zum Beispiel ist jede Erwähnung von „capturing groups" in der Beschreibung unten tatsächlich eine Funktionalität, die von RegExp.prototype[Symbol.replace]() bereitgestellt wird.

Wenn das pattern ein leerer String ist, wird das replacement an den Anfang des Strings gesetzt.

Eine Regex mit dem g-Flag ist der einzige Fall, in dem replace() mehr als einmal ersetzt. Weitere Informationen darüber, wie Regex-Eigenschaften (insbesondere das sticky-Flag) mit replace() interagieren, finden Sie unter RegExp.prototype[Symbol.replace]().

String als Ersetzung angeben: Der Ersetzungs-String kann die folgenden speziellen Ersetzungsmuster enthalten:

$$ – Fügt ein "$" ein.
$& – Fügt den übereinstimmenden Teilstring ein.
$` – Fügt den Teil des Strings ein, der dem übereinstimmenden Teilstring vorangeht.
$' – Fügt den Teil des Strings ein, der auf den übereinstimmenden Teilstring folgt.
$n – Fügt die n-te (1-indizierte) capturing group ein, wobei n eine positive ganze Zahl kleiner als 100 ist.
$<Name> – Fügt die benannte capturing group ein, wobei Name der Gruppenname ist.

$n und $<Name> sind nur verfügbar, wenn das pattern-Argument ein RegExp-Objekt ist. Wenn das pattern ein String ist oder die entsprechende capturing group in der Regex nicht vorhanden ist, wird das Muster wörtlich ersetzt. Wenn die Gruppe vorhanden, aber nicht übereingestimmt hat (weil sie Teil einer Disjunktion ist), wird sie durch einen leeren String ersetzt.

Funktion als Ersetzung angeben: Sie können eine Funktion als zweiten Parameter angeben. In diesem Fall wird die Funktion aufgerufen, nachdem die Übereinstimmung durchgeführt wurde. Das Ergebnis der Funktion (Rückgabewert) wird als Ersetzungs-String verwendet.

Die Funktion hat die folgende Signatur: function replacer(match, p1, p2, …, pN, offset, string, groups). Die Argumente sind: match (der übereinstimmende Teilstring), p1, p2, …, pN (der von jeder capture group gefundene String, sofern das erste Argument ein RegExp-Objekt ist), offset (der Offset des übereinstimmenden Teilstrings innerhalb des gesamten untersuchten Strings), string (der gesamte untersuchte String) und groups (ein Objekt, dessen Schlüssel die verwendeten Gruppennamen und dessen Werte die übereinstimmenden Teile sind; nur vorhanden, wenn das pattern mindestens eine benannte capturing group enthält).

Die genaue Anzahl der Argumente hängt davon ab, ob das erste Argument ein RegExp-Objekt ist – und wenn ja, wie viele capture groups es enthält. Die Funktion wird mehrmals für jede vollständige zu ersetzende Übereinstimmung aufgerufen, wenn der reguläre Ausdruck im ersten Parameter global ist.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	string \| RegExp \| Object	—	Kann ein String oder ein Objekt mit einer Symbol.replace-Methode sein – das typische Beispiel ist ein regulärer Ausdruck. Jeder Wert ohne Symbol.replace-Methode wird in einen String umgewandelt.
$replacement Pflicht	string \| Function	—	Kann ein String oder eine Funktion sein. Ist es ein String, ersetzt er den durch pattern übereinstimmenden Teilstring; es werden mehrere spezielle Ersetzungsmuster unterstützt. Ist es eine Funktion, wird sie für jede Übereinstimmung aufgerufen und ihr Rückgabewert als Ersetzungstext verwendet.

Rückgabewert

Typ

string

Beschreibung

Ein neuer String, in dem eines, mehrere oder alle Übereinstimmungen des pattern durch die angegebene Ersetzung ersetzt wurden.

Beispiele

Leeres Pattern

"xxx".replace("", "_"); // "_xxx"

Spezielle Ersetzungsmuster ohne passende Gruppe

"foo".replace(/(f)/, "$2");
// "$2oo"; the regex doesn't have the second group

"foo".replace("f", "$1");
// "$1oo"; the pattern is a string, so it doesn't have any groups

"foo".replace(/(f)|(g)/, "$2");
// "oo"; the second group exists but isn't matched

Funktion als Ersetzung mit capture groups

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is non-digits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(" - ");
}
const newString = "abc12345#$*%".replace(/(\D*)(\d*)(\W*)/, replacer);
console.log(newString); // abc - 12345 - #$*%

Regulären Ausdruck in replace() definieren

const str = "Twas the night before Xmas...";
const newStr = str.replace(/xmas/i, "Christmas");
console.log(newStr); // Twas the night before Christmas...

global- und ignoreCase-Flags mit replace() verwenden

const re = /apples/gi;
const str = "Apples are round, and apples are juicy.";
const newStr = str.replace(re, "oranges");
console.log(newStr); // oranges are round, and oranges are juicy.

Wörter in einem String vertauschen

const re = /(\w+)\s(\w+)/;
const str = "Maria Cruz";
const newStr = str.replace(re, "$2, $1");
console.log(newStr); // Cruz, Maria

Inline-Funktion, die die übereinstimmenden Zeichen modifiziert

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset > 0 ? "-" : "") + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

Funktioniert nicht (Auswertung als String-Literal)

// Won't work
const newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase());

Fahrenheit durch Celsius ersetzen

function f2c(x) {
  function convert(str, p1, offset, s) {
    return `${((p1 - 32) * 5) / 9}C`;
  }
  const s = String(x);
  const test = /(-?\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

Generischen Replacer erstellen

"abcd".replace(/(bc)/, (match, p1, offset) => `${match} (${offset}) `);
// "abc (1) d"

Fehlerhafter generischer Replacer mit rest parameters

function addOffset(match, ...args) {
  const offset = args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (abcd) d"

Korrekter generischer Replacer via Typprüfung

function addOffset(match, ...args) {
  const hasNamedGroups = typeof args.at(-1) === "object";
  const offset = hasNamedGroups ? args.at(-3) : args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (1) d"

// Wichtig · Fallstricke

Die oben genannten speziellen Ersetzungsmuster gelten nicht für Strings, die von der Replacer-Funktion zurückgegeben werden.

Siehe auch

String.prototype.replaceAll() String.prototype.match() RegExp.prototype.exec() RegExp.prototype.test() Symbol.replace RegExp.prototype[Symbol.replace]()

← Vorheriger Eintrag String.prototype.repeat() Nächster Eintrag → String.prototype.replaceAll()