String.prototype.replace()

Probieren Sie es aus

const paragraph = "This dog's name is just Dog! Yes, that is the name.";

console.log(paragraph.replace("name", "nickname"));
// Expected output: "This dog's nickname is just Dog! Yes, that is the name."

console.log(paragraph.replace(/\bis\b/, "was"));
// Expected output: "This dog's name was just Dog! Yes, that is the name."

console.log(paragraph.replace(/\bis\b/g, "was"));
// Expected output: "This dog's name was just Dog! Yes, that was the name."

Syntax

replace(pattern, replacement)

Parameter

pattern

Kann ein String oder ein Objekt mit einer Symbol.replace-Methode sein – ein typisches Beispiel ist ein regulärer Ausdruck. Jeder Wert ohne Symbol.replace-Methode wird in einen String umgewandelt.

replacement

Kann ein String oder eine Funktion sein.

• Wenn es ein String ist, ersetzt er den Teilstring, der mit pattern übereinstimmt. Es werden mehrere spezielle Ersetzungsmuster unterstützt; siehe den Abschnitt Einen String als Ersetzung angeben weiter unten.
• Wenn es eine Funktion ist, wird sie für jede Übereinstimmung aufgerufen. Ihr Rückgabewert wird als Ersetzungstext verwendet. Die an diese Funktion übergebenen Argumente werden im Abschnitt Eine Funktion als Ersetzung angeben weiter unten beschrieben.

Rückgabewert

Ein neuer String, in dem eine, mehrere oder alle Übereinstimmungen mit dem Muster durch die angegebene Ersetzung ersetzt wurden.

Beschreibung

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

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

Wenn pattern ein Objekt mit einer Symbol.replace-Methode ist (einschließlich RegExp-Objekten), wird diese Methode mit dem Zielstring 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 Methode [Symbol.replace]() bestimmt – beispielsweise wird jede unten beschriebene Funktionalität von „Capturing Groups“ tatsächlich durch RegExp.prototype[Symbol.replace]() bereitgestellt.

Wenn pattern ein leerer String ist, wird die Ersetzung dem Anfang des Strings vorangestellt.

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

Ein regulärer Ausdruck mit dem Flag g ist der einzige Fall, in dem replace() mehr als eine Ersetzung vornimmt. Weitere Informationen dazu, wie Eigenschaften regulärer Ausdrücke (insbesondere das Flag sticky) mit replace() zusammenwirken, finden Sie unter RegExp.prototype[Symbol.replace]().

Einen String als Ersetzung angeben

Der Ersetzungsstring kann die folgenden speziellen Ersetzungsmuster enthalten:

$n und $<Name> sind nur verfügbar, wenn das Argument pattern ein RegExp-Objekt ist. Wenn pattern ein String ist oder die entsprechende Capturing Group im regulären Ausdruck nicht vorhanden ist, wird das Muster als Literal ersetzt. Wenn die Gruppe vorhanden ist, aber keine Übereinstimmung aufweist (weil sie Teil einer Alternative ist), wird sie durch einen leeren String ersetzt.

"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

Eine Funktion als Ersetzung angeben

Sie können als zweiten Parameter eine Funktion angeben. In diesem Fall wird die Funktion aufgerufen, nachdem die Übereinstimmung ermittelt wurde. Das Ergebnis der Funktion (ihr Rückgabewert) wird als Ersetzungsstring verwendet.

Die Funktion hat die folgende Signatur:

function replacer(match, p1, p2, /* …, */ pN, offset, string, groups) {
  return replacement;
}

Die Argumente der Funktion sind:

match

Der übereinstimmende Teilstring. (Entspricht dem oben genannten $&.)

p1, p2, …, pN

Der n-te durch eine Capturing Group gefundene String (einschließlich benannter Capturing Groups), sofern das erste Argument von replace() ein RegExp-Objekt ist. (Entspricht den oben genannten $1, $2 usw.) Wenn pattern beispielsweise /(\a+)(\b+)/ ist, enthält p1 die Übereinstimmung für \a+ und p2 die Übereinstimmung für \b+. Wenn die Gruppe Teil einer Alternative ist (z. B. "abc".replace(/(a)|(b)/, replacer)), ist die nicht übereinstimmende Alternative undefined.

offset

Die Position des übereinstimmenden Teilstrings innerhalb des gesamten untersuchten Strings. Wenn der gesamte String beispielsweise 'abcd' und der übereinstimmende Teilstring 'bc' ist, hat dieses Argument den Wert 1.

string

Der gesamte untersuchte String.

groups

Ein Objekt, dessen Schlüssel die verwendeten Gruppennamen und dessen Werte die übereinstimmenden Teile sind (undefined, wenn keine Übereinstimmung vorliegt). Nur vorhanden, wenn 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, falls ja, wie viele Capturing Groups es enthält.

Im folgenden Beispiel wird newString auf 'abc - 12345 - #$*%' gesetzt:

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 - #$*%

Wenn der reguläre Ausdruck im ersten Parameter global ist, wird die Funktion für jede zu ersetzende vollständige Übereinstimmung aufgerufen.

Beispiele

Den regulären Ausdruck in replace() definieren

Im folgenden Beispiel wird der reguläre Ausdruck in replace() definiert und enthält das Flag zum Ignorieren der Groß- und Kleinschreibung.

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

Dies gibt 'Twas the night before Christmas...' aus.

Die Flags global und ignoreCase mit replace() verwenden

Eine globale Ersetzung ist nur mit einem regulären Ausdruck möglich. Im folgenden Beispiel enthält der reguläre Ausdruck die Flags für globale Suche und zum Ignorieren der Groß- und Kleinschreibung. Dadurch kann replace() jedes Vorkommen von 'apples' im String durch 'oranges' ersetzen.

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.

Dies gibt 'oranges are round, and oranges are juicy' aus.

Wörter in einem String vertauschen

Das folgende Skript vertauscht die Wörter im String. Für den Ersetzungstext verwendet das Skript Capturing Groups und die Ersetzungsmuster $1 und $2.

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

Dies gibt 'Cruz, Maria' aus.

Eine Inline-Funktion verwenden, die die übereinstimmenden Zeichen verändert

In diesem Beispiel werden alle Großbuchstaben im String in Kleinbuchstaben umgewandelt und unmittelbar vor der jeweiligen Übereinstimmung wird ein Bindestrich eingefügt. Entscheidend ist dabei, dass das übereinstimmende Element weiterverarbeitet werden muss, bevor es als Ersetzung zurückgegeben wird.

Die Ersetzungsfunktion nimmt den übereinstimmenden Ausschnitt als Parameter entgegen. Sie verwendet ihn, um die Groß- und Kleinschreibung zu ändern und den Bindestrich voranzustellen, bevor sie das Ergebnis zurückgibt.

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

Für styleHyphenFormat('borderTop') wird 'border-top' zurückgegeben.

Da wir das Ergebnis der Übereinstimmung vor der endgültigen Ersetzung weiterverarbeiten möchten, müssen wir eine Funktion verwenden. So wird die Übereinstimmung vor dem Aufruf der Methode toLowerCase() ausgewertet. Wenn wir versucht hätten, dies ohne Funktion mit der Übereinstimmung zu tun, hätte toLowerCase() keine Wirkung.

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

Der Grund dafür ist, dass '$&'.toLowerCase() zunächst als String-Literal ausgewertet würde (mit demselben '$&' als Ergebnis), bevor die Zeichen als Muster verwendet werden.

Einen Fahrenheit-Temperaturwert durch sein Celsius-Äquivalent ersetzen

Das folgende Beispiel ersetzt einen Fahrenheit-Temperaturwert durch den entsprechenden Celsius-Temperaturwert. Der Fahrenheit-Wert muss eine Zahl sein, die mit "F" endet. Die Funktion gibt die Celsius-Zahl mit der Endung "C" zurück. Wenn die Eingabezahl beispielsweise "212F" ist, gibt die Funktion "100C" zurück. Ist die Zahl "0F", gibt die Funktion "-17.77777777777778C" zurück.

Der reguläre Ausdruck test prüft auf eine beliebige Zahl, die mit F endet. Die Anzahl der Fahrenheit-Grade ist für die Funktion über ihren zweiten Parameter p1 zugänglich. Die Funktion berechnet die Celsius-Zahl anhand der Fahrenheit-Gradzahl, die der Funktion f2c() als String übergeben wird. f2c() gibt anschließend die Celsius-Zahl zurück. Diese Funktion ahmt das Flag s///e von Perl nach.

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);
}

Eine generische Ersetzungsfunktion erstellen

Angenommen, wir möchten eine Ersetzungsfunktion erstellen, die an jeden übereinstimmenden String die Positionsangabe anhängt. Da die Ersetzungsfunktion den Parameter offset bereits erhält, ist dies einfach, wenn der reguläre Ausdruck im Voraus bekannt ist.

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

Diese Ersetzungsfunktion lässt sich jedoch nur schwer verallgemeinern, wenn sie mit beliebigen regulären Ausdrücken funktionieren soll. Die Ersetzungsfunktion ist variadisch – die Anzahl ihrer Argumente hängt von der Anzahl der vorhandenen Capturing Groups ab. Wir können Rest-Parameter verwenden, doch damit würden auch offset, string usw. im Array erfasst. Da groups je nach regulärem Ausdruck übergeben werden kann oder auch nicht, ist es außerdem schwierig, allgemeingültig zu bestimmen, welches Argument offset entspricht.

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"

Das obige Beispiel addOffset funktioniert nicht, wenn der reguläre Ausdruck eine benannte Gruppe enthält. In diesem Fall wäre args.at(-2) nämlich string statt offset.

Stattdessen müssen Sie die letzten Argumente anhand ihres Typs bestimmen, da groups ein Objekt und string ein String ist.

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"

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill für String.prototype.replace in core-js mit Korrekturen und Implementierung modernen Verhaltens wie der Unterstützung von Symbol.replace
• Leitfaden zu regulären Ausdrücken
• String.prototype.replaceAll()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.replace
• RegExp.prototype[Symbol.replace]()