Signatur
Beschreibung
Symbol.replace ist ein wohlbekanntes Symbol (well-known symbol). Es dient als Eigenschaftsschlüssel für eine Methode, die festlegt, wie ein Objekt Text in einer Zeichenkette ersetzt. Wenn du str.replace(muster, ersatz) oder str.replaceAll(muster, ersatz) aufrufst und muster weder undefined noch null ist, sucht die Engine zuerst nach muster[Symbol.replace]. Ist dort eine Methode vorhanden, wird sie als muster[Symbol.replace](str, ersatz) aufgerufen. Ihr Rückgabewert ist dann das Ergebnis von replace().
Der bekannteste Anwender ist RegExp.prototype[Symbol.replace]. Genau darüber funktionieren reguläre Ausdrücke in replace(). Ohne diese Methode wird das Muster in eine Zeichenkette umgewandelt, und nur das erste Vorkommen wird wörtlich ersetzt.
In der Praxis brauchst du Symbol.replace vor allem für:
- Eigene Muster-Objekte, zum Beispiel Platzhalter-Vorlagen, Tokenizer oder Suchen ohne Beachtung von Groß- und Kleinschreibung, die sich direkt an
replace()übergeben lassen. - Unterklassen von
RegExp, die das Ersetzen erweitern, etwa durch Protokollierung, Zähler oder Nachbearbeitung.
Die Eigenschaft selbst kannst du weder überschreiben noch aufzählen oder umkonfigurieren (writable: false, enumerable: false, configurable: false).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Parameter der Methode [Symbol.replace], nicht der Eigenschaft selbst: die Zeichenkette, auf der replace()/replaceAll() aufgerufen wurde (der this-Wert des Aufrufs). |
|
| $replacement Pflicht | string | Function | any | Das zweite Argument von replace(). Es wird unverändert weitergereicht. Eigene Implementierungen können hier also auch Objekte entgegennehmen, zum Beispiel ein Datenobjekt für Platzhalter. |
Rückgabewert
Symbol(Symbol.replace). Eine unter diesem Schlüssel hinterlegte Methode sollte eine Zeichenkette zurückgeben. Dieser Wert wird zum Ergebnis von replace() bzw. replaceAll().Beispiele
Eigenes Muster-Objekt ersetzt alle Vorkommen
class WortErsetzer {
constructor(wort) {
this.wort = wort;
}
// Wird von String.prototype.replace aufgerufen
[Symbol.replace](str, ersatz) {
return str.split(this.wort).join(ersatz);
}
}
const text = 'foo-bar-foo';
console.log(text.replace(new WortErsetzer('foo'), 'baz'));Platzhalter-Vorlage mit Datenobjekt als Ersatz
const platzhalter = {
[Symbol.replace](str, daten) {
// Das zweite Argument wird unverändert übergeben – hier ein Objekt
return str.replace(/\{(\w+)\}/g, (treffer, schluessel) =>
schluessel in daten ? String(daten[schluessel]) : treffer
);
}
};
const vorlage = 'Hallo {name}, du hast {anzahl} neue Nachrichten. {rest}';
console.log(vorlage.replace(platzhalter, { name: 'Anna', anzahl: 3 }));RegExp-Unterklasse mit Protokollierung
class LogRegExp extends RegExp {
[Symbol.replace](str, ersatz) {
const ergebnis = super[Symbol.replace](str, ersatz);
console.log(`${this} : "${str}" -> "${ergebnis}"`);
return ergebnis;
}
}
const datum = '2024-01-15'.replace(new LogRegExp('-', 'g'), '.');
console.log(datum);Symbol untersuchen und direkt aufrufen
console.log(typeof Symbol.replace);
console.log(Symbol.replace.toString());
// Die eingebaute RegExp-Methode lässt sich auch direkt aufrufen
console.log(/a/g[Symbol.replace]('banana', 'o'));
// Zeichenketten besitzen keine eigene Symbol.replace-Methode
console.log('abc'[Symbol.replace]);