このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docsコミュニティーについてもっと知り、仲間になるにはこちらから。
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 2020年1月.
[Symbol.replace]() はRegExp インスタンスのメソッドで、正規表現がパターンとして渡されたときにString.prototype.replace() およびString.prototype.replaceAll() がどのように動作するかを指定します。
試してみましょう
class RegExp1 extends RegExp { [Symbol.replace](str) { return RegExp.prototype[Symbol.replace].call(this, str, "#!@?"); }}console.log("football".replace(new RegExp1("foo")));// 予想される結果: "#!@?tball"構文
regexp[Symbol.replace](str, replacement)引数
str置換の対象となる文字列 (
String) です。replacement文字列または関数を取ることができます。
- 文字列の場合は、現在の正規表現で一致した部分文字列をそれで置き換えます。特殊な置換パターンの数値に対応しています。
String.prototype.replaceページの置換文字列としての文字列の指定の節を参照してください。 - 関数の場合は、一致するごとに呼び出され、返値が置換文字列として使用されます。この関数に提供される引数については、
String.prototype.replaceページの置換文字列としての関数の指定で記述されています。
- 文字列の場合は、現在の正規表現で一致した部分文字列をそれで置き換えます。特殊な置換パターンの数値に対応しています。
返値
一部またはすべてのパターンの一致箇所が置換内容によって置き換えられた新しい文字列です。
解説
このメソッドはString.prototype.replace() の中で、pattern 引数がRegExp オブジェクトであった場合に内部的に呼び出されます。たとえば、次の 2 つの例は同じ結果を返します。
"abc".replace(/a/, "A");/a/[Symbol.replace]("abc", "A");正規表現がグローバル（g フラグ付き）である場合、正規表現のexec() メソッドはexec() がnull を返すまで繰り返し呼び出されます。そうでない場合、exec() は一度だけ呼び出されます。それぞれのexec() の結果に対して、String.prototype.replace() の解説に基づいて置き換える準備をします。
[Symbol.replace]() はexec() がnull を返すまで呼び続け、最後の照合に失敗すると自動的に正規表現のlastIndex を 0 にリセットするので、[Symbol.replace]() が終了しても通常は副作用がありません。しかし、正規表現が粘着的かつグローバルではない場合、lastIndex はリセットされません。この場合、replace() を呼び出すたびに異なる結果を返す可能性があります。
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正規表現が粘着的でグローバルな場合、粘着的に照合します。すなわち、lastIndex 以降の出現には一致しません。
console.log("aa-a".replace(/a/gy, "b")); // "bb-a"もし現在の一致が空文字列であったとしても、lastIndex は進みます。正規表現がUnicode 対応であれば、Unicode コードポイントが 1 つ進みます。そうでない場合は、 UTF-16 コード単位 1 つ分進みます。
console.log("😄".replace(/(?:)/g, " ")); // " \ud83d \ude04 "console.log("😄".replace(/(?:)/gu, " ")); // " 😄 "このメソッドは、RegExp サブクラスの置換動作をカスタマイズするために存在しています。
例
直接呼出し
this と引数の順序が異なる点を除いて、このメソッドはString.prototype.replace() とほとんど同じ使い方ができます。
const re = /-/g;const str = "2016-01-01";const newStr = re[Symbol.replace](str, ".");console.log(newStr); // 2016.01.01サブクラスでの[Symbol.replace]() の使用
既定の動作を修正するために、RegExp のサブクラスで[Symbol.replace]() メソッドをオーバーライドできます。
class MyRegExp extends RegExp { constructor(pattern, flags, count) { super(pattern, flags); this.count = count; } [Symbol.replace](str, replacement) { // [Symbol.replace]() を `count` 回実行する 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 は re[Symbol.replace]() を呼び出すconsole.log(newStr); // ###34567仕様書
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-regexp.prototype-%symbol.replace% |