RegExp.prototype[Symbol.replace]()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die Methode [Symbol.replace]() von RegExp-Instanzen legt fest, wie String.prototype.replace() und String.prototype.replaceAll() sich verhalten sollen, wenn der reguläre Ausdruck als Muster übergeben wird.

Probieren Sie es aus

class RegExp1 extends RegExp {
  [Symbol.replace](str) {
    return RegExp.prototype[Symbol.replace].call(this, str, "#!@?");
  }
}

console.log("football".replace(new RegExp1("foo")));
// Expected output: "#!@?tball"

Syntax

js
regexp[Symbol.replace](str, replacement)

Parameter

str

Ein String, der das Ziel des Ersetzens ist.

replacement

Kann eine Zeichenkette oder eine Funktion sein.

  • Wenn es eine Zeichenkette ist, ersetzt sie den Teilstring, der durch den aktuellen regulären Ausdruck gematcht wurde. Eine Reihe von speziellen Ersetzungsmustern wird unterstützt; siehe den Abschnitt Eine Zeichenkette als Ersatz angeben von String.prototype.replace.
  • Wenn es eine Funktion ist, wird sie für jeden Treffer aufgerufen, und der Rückgabewert wird als Ersetzungstext verwendet. Die an diese Funktion übergebenen Argumente sind im Abschnitt Eine Funktion als Ersatz angeben von String.prototype.replace beschrieben.

Rückgabewert

Ein neuer String, in dem ein, einige oder alle Treffer des Musters durch den angegebenen Ersatz ersetzt wurden.

Beschreibung

Diese Methode wird intern in String.prototype.replace() und String.prototype.replaceAll() aufgerufen, wenn das pattern-Argument ein RegExp-Objekt ist. Zum Beispiel liefern die folgenden zwei Beispiele dasselbe Ergebnis.

js
"abc".replace(/a/, "A");

/a/[Symbol.replace]("abc", "A");

Wenn der reguläre Ausdruck global ist (mit dem g-Flag), wird die Methode exec() des regulären Ausdrucks wiederholt aufgerufen, bis exec() null zurückgibt. Andernfalls wird exec() nur einmal aufgerufen. Für jedes Ergebnis von exec() wird die Ersetzung gemäß der Beschreibung in String.prototype.replace() vorbereitet.

Da [Symbol.replace]() exec() so lange aufrufen würde, bis es null zurückgibt, und exec() den lastIndex des regulären Ausdrucks automatisch auf 0 zurücksetzt, wenn der letzte Treffer fehlschlägt, hätte [Symbol.replace]() normalerweise keine Nebenwirkungen beim Beenden. Wenn der reguläre Ausdruck jedoch sticky ist, aber nicht global, wird lastIndex nicht zurückgesetzt. In diesem Fall kann jeder Aufruf von replace() ein anderes Ergebnis liefern.

js
const re = /a/y;

for (let i = 0; i < 5; i++) {
  console.log("aaa".replace(re, "b"), re.lastIndex);
}

// baa 1
// aba 2
// aab 3
// aaa 0
// baa 1

Wenn der reguläre Ausdruck sticky und global ist, werden dennoch sticky-Matches durchgeführt — d.h. es gelingt nicht, Vorkommen jenseits von lastIndex zu finden.

js
console.log("aa-a".replace(/a/gy, "b")); // "bb-a"

Wenn der aktuelle Treffer ein leerer String ist, wird lastIndex trotzdem vorgerückt — falls der reguläre Ausdruck Unicode-fähig ist, wird es um einen Unicode-Codepunkt vorgerückt; andernfalls erfolgt der Vorstoß um eine UTF-16-Codeeinheit.

js
console.log("😄".replace(/(?:)/g, " ")); // " \ud83d \ude04 "
console.log("😄".replace(/(?:)/gu, " ")); // " 😄 "

Diese Methode dient dazu, das Ersetzungsverhalten in RegExp-Unterklassen anzupassen.

Beispiele

Direkter Aufruf

Diese Methode kann fast auf die gleiche Weise wie String.prototype.replace() verwendet werden, mit dem Unterschied, dass die Reihenfolge von this und den Argumenten anders ist.

js
const re = /-/g;
const str = "2016-01-01";
const newstr = re[Symbol.replace](str, ".");
console.log(newstr); // 2016.01.01

Verwendung von [Symbol.replace]() in Unterklassen

Unterklassen von RegExp können die Methode [Symbol.replace]() überschreiben, um das Standardverhalten zu ändern.

js
class MyRegExp extends RegExp {
  constructor(pattern, flags, count) {
    super(pattern, flags);
    this.count = count;
  }
  [Symbol.replace](str, replacement) {
    // Perform [Symbol.replace]() `count` times.
    let result = str;
    for (let i = 0; i < this.count; i++) {
      result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
    }
    return result;
  }
}

const re = new MyRegExp("\\d", "", 3);
const str = "01234567";
const newstr = str.replace(re, "#"); // String.prototype.replace calls re[Symbol.replace]().
console.log(newstr); // ###34567

Spezifikationen

Specification
ECMAScript® 2025 Language Specification
# sec-regexp.prototype-%symbol.replace%

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.replace]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch