--- title: String.prototype.replace() slug: Web/JavaScript/Reference/Global_Objects/String/replace tags: - Expressions - JavaScript - Methods - Prototype - Reference - Regular - String translation_of: Web/JavaScript/Reference/Global_Objects/String/replace ---
{{JSRef}}

replace() メソッドは、pattern にマッチした文字列の一部またはすべてを replacement で置き換えた新しい文字列を返します。pattern は文字列または {{jsxref("RegExp")}}、replacement は文字列または各マッチで呼び出される関数です。pattern が文字列の場合、最初に一致した箇所のみを置き換えます。

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

{{EmbedInteractiveExample("pages/js/string-replace.html")}}

構文

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

引数

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

戻り値

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

詳細

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

グローバルな検索と置換を動作させるためには、正規表現に g フラグを含める必要があります。

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

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

パターン 挿入
$$ "$" を挿入します。
$& マッチした部分文字列を挿入します。
$` マッチした部分文字列の直前の文字列の部分を挿入します。
$' マッチした部分文字列の直後の文字列の部分を挿入します。
$n n は 100 未満の正の整数です。第一引数が {{jsxref("RegExp")}} オブジェクトだった場合に n 番目の括弧でキャプチャされた文字列を挿入します。1, 2, ... でインデックスされることに注意してください。

引数としての関数の指定

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

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

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

（引数の正確な個数は、第一引数が {{jsxref("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 オブジェクトからなる配列を生成します。

仕様

仕様書 策定状況 コメント
{{SpecName('ES3')}} {{Spec2('ES3')}} 初期定義。JavaScript 1.2 で実装される。
{{SpecName('ES5.1', '#sec-15.5.4.11', 'String.prototype.replace')}} {{Spec2('ES5.1')}}  
{{SpecName('ES6', '#sec-string.prototype.replace', 'String.prototype.replace')}} {{Spec2('ES6')}}  
{{SpecName('ESDraft', '#sec-string.prototype.replace', 'String.prototype.replace')}} {{Spec2('ESDraft')}}  

ブラウザー実装状況

{{Compat("javascript.builtins.String.replace")}}

Firefox 固有の注記

関連情報