replace() メソッドは、pattern にマッチした文字列の一部または全てを replacement で置き換えた新しい文字列を返します。pattern は文字列または RegExpreplacement は文字列または各マッチで呼び出される関数です。

注記: 元の文字列は変更されません。

構文

str.replace(regexp|substr, newSubstr|function)

パラメーター

regexp (pattern)
リテラルまたはRegExp オブジェクトです。マッチすると、第2引数の newSubStr または function の戻り値と置き換えられます。
substr (pattern)
newSubStr に置き換えられる String。これは逐次的な文字列として扱われ、正規表現としては解釈されません。最初に出てきたものだけが置き換えられます。
newSubStr (replacement)
regexpsubstr パラメーターで指定される部分文字列を置換する String 。数々の特別な置換パターンがサポートされます; 下記の "Specifying a string as a parameter" 節を見てください。
function (replacement)
新しい部分文字列を生成するために実行される関数で、regexpsubstr でマッチしたものを置き換えるのに使われます。この関数に渡される引数は下記の "Specifying a function as a parameter" で述べられています。

戻り値

パターンにマッチした部分文字列の一部または全てを置換文字列で置き換えた新しい文字列。

詳細

このメソッドは、それを呼び出した String オブジェクトを変化させません。戻り値として新しい文字列を返します。

グローバルな検索と置換を動作させるためには、正規表現に g フラグを含めるか、第一引数が文字列である場合には flags 引数に g を含める必要があります。

引数としての文字列の指定

置換文字列には以下の特殊な置換パターンを含めることができます。

パターン 挿入
$$ "$" を挿入します。
$& マッチした部分文字列を挿入します。
$` マッチした部分文字列の直前の文字列の部分を挿入します。
$' マッチした部分文字列の直後の文字列の部分を挿入します。
$n n は 100以下の正の整数が入ります。第一引数が RegExp オブジェクトだった場合、n 番目の括弧でキャプチャされたサブマッチの文字列を挿入します。これは 1-でインデックスされるのにご注意ください。

引数としての関数の指定

第二引数として関数を指定することができます。このとき、関数はマッチが完了された後に実行されます。関数呼び出しの結果(返り値)は、置換文字列として使われます(注記: 上記の特殊な置換パターンはこの場合には適用されません)。第一引数の正規表現がグローバルだと、置換されるべきマッチごとに関数が複数回実行されうることに注意してください。

関数に与えられる引数は次の通りです。

名前 与えられる値
match マッチした部分文字列(上記の $& に対応)。
p1, p2, ... replace() の第一引数が RegExp オブジェクトだった場合、n 番目の括弧でキャプチャされたサブマッチの文字列(上記の $1, $2, などに対応)。例えば /(\a+)(\b+)/ が与えられた場合、p1\a+ に対するマッチ、p2\b+ に対するマッチとなります。
offset マッチした部分文字列の、分析中の文字列全体の中でのオフセット(例えば、文字列全体が 'abcd' で、マッチした部分文字列が 'bc' ならば、この引数は 1 となります)。
string 分析中の文字列全体。

(引数の正確な個数は、第一引数が RegExp オブジェクトかどうか、そうならばさらに括弧でキャプチャされるサブマッチがいくつ指定されているかに依ります。)

以下の例は newString'abc - 12345 - #$*%' をセットします。

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
var newString = 'abc12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);
console.log(newString);  // abc - 12345 - #$*%

replace() で正規表現を利用する

以下の例では、replace メソッドで正規表現を利用しています。

var str = 'Twas the night before Xmas...';
var newstr = str.replace(/xmas/i, 'Christmas');
console.log(newstr);  // Twas the night before Christmas...

ignore フラグと global フラグの利用

グローバルな置換は正規表現だけで行われます。以下の例では、正規表現で大文字と小文字の違いを無視するフラグ (i) とグローバルマッチのフラグ (g)を利用し replace() は'apples'が出てくるたびに'oranges'に置換します。

var re = /apples/gi;
var str = 'Apples are round, and apples are juicy.';
var newstr = str.replace(re, 'oranges');
console.log(newstr);  // oranges are round, and oranges are juicy.

この出力は 'oranges are round, and oranges are juicy' となります。

文字列内の単語の交換

文字列内の単語の位置を交換します。$1$2 を置き換えるパターンを使用しています。

var re = /(\w+)\s(\w+)/;
var str = 'John Smith';
var newstr = str.replace(re, '$2, $1');
console.log(newstr);  // Smith, John

この出力は 'Smith, John' となります。

マッチした文字を修正するインライン関数の使用

次の例では、文字列内に出現する大文字の全ては小文字に変換され、ハイフンがマッチした位置の直前に挿入されます。ここで重要なことは、追加の操作は、マッチしたアイテムが置換されて戻される前に必要とされるということです。

置換する関数はマッチした断片をその関数の引数として適用します。そして、その引数を大文字小文字変形し、戻り値の直前にハイフンを連結します。

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

styleHyphenFormat('borderTop')を入力すると 'border-top'を返します。

最終的な置換が作成される前にサブマッチの結果 をさらに変形したい場合、関数を使わなくてはなりません。これは、toLowerCase() メソッドの前にマッチを評価することを強制します。関数無しにこれをマッチに使用した場合、その toLowerCase() メソッドは効果がないでしょう。

var newString = propertyName.replace(/[A-Z]/, '-' + '$&'.toLowerCase());  // 動作しないでしょう

これは、'$&'.toLowerCase() は、まずその文字がパターンとして使用される前に ('$&' という結果である ) 文字列リテラルとして評価されるだろうからです。

華氏温度を同等の摂氏温度と置き換える

以下の例は、ある華氏温度をそれと同等の摂氏温度と置き換えます。その華氏温度は F で終わる数でなければなりません。その関数は C で終わる摂氏を返します。例えば、入力される数が 212F である場合、その関数は 100C を返します。入力される数が 0F であった場合、その関数は -17.77777777777778C を返します。

その正規表現 test は、任意の数が F で終わっているかチェックします。華氏温度の数は、関数の 第二引数 p1 を通して、その関数にアクセスできます。その関数は文字列内で渡された華氏温度をベースとした摂氏の数を f2c にセットします。それから、f2c は、摂氏の数を返します。この関数は Perl の s///e フラグ 【訳注: s は substitute (置換する)の略。e は evaluate(評価する)の略です。詳細は perlop の Regexp Quote-Like Operators の項※perldoc.jp による日本語訳)を参照してください。】 と似ています。

function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1 - 32) * 5/9) + 'C';
  }
  var s = String(x);
  var test = /(-?\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

インライン関数と正規表現で for ループを回避する

次の例では、あるパターンを持つ文字列を解析してオブジェクトの配列に変換します。

入力:

x, -, _ からなる文字列です。

x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___

出力ルール:

'x''on' への切り替えを、'-' (ハイフン) は 'off' への切り替えを表すとし、'_' (アンダースコア) は x の後に続いて 'on' の長さを表すものとします。on と off の切り替わりをオブジェクトの配列で返します。

[
  { on: true, length: 1 },   // 一番最初の "x" で on になります。
  { on: false, length: 1 },  // その次の "-" で off になります。
  { on: true, length: 2 }    // その次の "x" で on になり、"_" が一つ続いているため、長さは 2 になります。
  ...
]

スニペット:

var str = 'x-x_';
var retArr = [];
str.replace(/(x_*)|(-)/g, function(match, p1, p2) {
  if (p1) { retArr.push({ on: true, length: p1.length }); }
  if (p2) { retArr.push({ on: false, length: 1 }); }
});

console.log(retArr);

このスニペットは for を使わずに、上記の入出力ルールを満たす 3 オブジェクトからなる配列を生成します。

仕様

仕様書 策定状況 コメント
ECMAScript 3rd Edition (ECMA-262) 標準 初期定義。JavaScript 1.2 で実装される。
ECMAScript 5.1 (ECMA-262)
String.prototype.replace の定義
標準  
ECMAScript 2015 (6th Edition, ECMA-262)
String.prototype.replace の定義
標準  
ECMAScript Latest Draft (ECMA-262)
String.prototype.replace の定義
ドラフト  

ブラウザー実装状況

機能ChromeEdgeFirefoxInternet ExplorerOperaSafari
基本対応 あり あり1 あり あり あり
flags なし なし1 — 49 なし なし なし
機能Android webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
基本対応 あり あり あり4 あり あり あり
flags なし なし なし4 — 49 なし なし なし

Firefox 固有の注記

  • flags は Gecko のみで利用できる非標準の第3引数です : str.replace(regexp|substr, newSubStr|function, flags)
  • Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24) 以降、このメソッドは ECMAScript 標準に準拠するために補正されました。replace() がグローバルの正規表現とともに呼び出された場合、RegExp.lastIndex プロパティが(もし指定されていたなら)0 にリセットされます (バグ 501739)。
  • Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36) 以降、flags 引数は非推奨となり、コンソールに警告を投げます (バグ 1142351)。
  • Gecko 47 (Firefox 47 / Thunderbird 47 / SeaMonkey 2.44) 以降、非標準の flags 引数は非リリース版でサポートされず、もうすぐ完全に削除されます (バグ 1245801).
  • Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46) 以降、非標準の flags 引数はもうサポートされません (バグ 1108382).

関連情報

ドキュメントのタグと貢献者

このページの貢献者: Uemmra3, woodmix, mamodayo, mitsuba-clover, teoli, ethertank, Potappo, Mgjbot
最終更新者: Uemmra3,