RegExp.prototype[@@replace]()

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis janvier 2020.

La méthode [@@replace]() remplace toutes ou certaines correspondances d'un motif this dans une chaîne de caractère avec un outil de remplacement. La valeur renvoyée est la nouvelle chaîne ainsi créée. Cet outil de remplacement peut être une chaîne de caractère ou une fonction appelée pour chacune des correspondances.

Dans cet article

Exemple interactif

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"

Syntaxe

regexp[Symbol.replace](str, newSubStr|function)

Paramètres

str

Une chaîne de caractères (String) pour laquelle on souhaite effectuer des remplacement.

newSubStr (replacement)

La chaîne de caractères qui remplace les correspondances trouvées. On peut effectuer le remplacement sur un nombre donné de correspondances (cf. la section Utiliser une chaîne de caractères comme paramètre de la page String.prototype.replace()).

function (replacement)

Une fonction qui est appelée pour créer la sous-chaîne de remplacement. Les arguments fournis à cette fonction sont décrits dans la section Utiliser une chaîne de caractères comme paramètre de la page String.prototype.replace().

Valeur de retour

Une nouvelle chaîne de caractères pour laquelle les correspondances (toutes ou une partie) ont été remplacées.

Description

Cette méthode est appelée de façon interne par la méthode String.prototype.replace() lorsque l'arugment pattern argument est un objet RegExp. Les deux lignes de code qui suivent sont équivalentes et la seconde est la version interne de la première :

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

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

Cette méthode existe afin de pouvoir personnaliser le comportement du remplacement pour les classes filles de RegExp.

Si l'argument décrivant le motif n'est pas un objet RegExp, String.prototype.replace() n'appellera pas cette méthode et ne créera pas d'objet RegExp.

Exemples

Appel direct

Cette méthode peut être utilisée comme String.prototype.replace(), aux différences près que l'objet this est différent et que l'ordre des arguments change :

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

Utiliser @@replace dans une sous-classe

Les sous-classes de RegExp peuvent surcharger la méthode [@@replace]() pour modifier le comportement.

js
class MaRegExp extends RegExp {
  constructor(pattern, flags, count) {
    super(pattern, flags);
    this.count = count;
  }
  [Symbol.replace](str, replacement) {
    // Applique @@replace |count| fois.
    var result = str;
    for (var i = 0; i < this.count; i++) {
      result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
    }
    return result;
  }
}

var re = new MaRegExp("\\d", "", 3);
var str = "01234567";
var newstr = str.replace(re, "#"); // String.prototype.replace appelle re[@@replace].
console.log(newstr); // ###34567

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 17 févr. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

Objets natifs standards
RegExp
Constructeur
1. Constructeur RegExp()
Méthodes statiques
1. escape()
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
Héritage
Object/Function
Méthodes statiques
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
1. Object.prototype.__proto__
2. Object.prototype.constructor