本文へスキップ
FrAIFlow

トラブル解決 / テキスト・コード

JavaScriptの置換文字列がドル記号で変わる理由

検索・置換ツールで、置換後の文章そのものが変わってしまうことがあります。検索が普通の文字列でも、JavaScriptは置換引数にあるドル記号の並びを解釈します。入力どおりの文章を入れたいなら、関数からその文章を返してください。

一つの値が二通りに解釈される
保存済みの例に基づく筆者作成の説明図です。アプリのスクリーンショットではありません。

入力を変える前に、置換テンプレートの規則を確認する

プレースホルダーを、$&を含む料金の説明に置き換える場面を考えてください。この2文字をそのまま入れたいのに、元のプレースホルダーが再び現れます。必ずしも文字コードの問題ではありません。検索に正規表現ではなく普通の文字列を使っていても、置換引数には小さなテンプレート言語の規則があります。

文章のコピーと一致箇所一つで試しましょう。ドル記号の並びが変わるなら、置換引数をコールバックに切り替えて結果を比較します。この比較中は検索条件を変えないでください。両方を一度に変えると、どの規則が原因か分かりにくくなります。

2012年の公開相談では、文字列全体を$'で置き換えたところ、結果が空になりました。このトークンは一致箇所の後ろの部分を意味します。一致が文字列全体を含んでいたため、後ろには何もなかったのです。

const input = "as";
const replacement = "$'";
input.replace("as", replacement);       // ""
input.replace("as", () => replacement); // "$'"

保存済みのNode.js v24.19.0テストでは、両方の結果を再現しました。ほかにも置換トークンとして、ドル記号そのものを表す$$、一致箇所を表す$&、パターンに対応するグループがある場合の$1のようなキャプチャ参照があります。前方部分や名前付きキャプチャの形式もあります。ただし、単独のドル記号が常に特別な意味を持つわけではありません。

文字列置換とテンプレート置換を明示的に分ける
保存済みの例に基づく筆者作成の説明図です。アプリのスクリーンショットではありません。

利用者の文章をそのまま入れるならコールバックを使う

const draft = "Price: TOKEN. Repeat: TOKEN.";
const typedReplacement = "$& costs $$";

console.log(draft.replaceAll("TOKEN", typedReplacement));
// Price: TOKEN costs $. Repeat: TOKEN costs $.

console.log(draft.replaceAll("TOKEN", () => typedReplacement));
// Price: $& costs $$. Repeat: $& costs $$.

一つ目の呼び出しでは置換文字列が解釈されます。二つ目では一致するたびに関数が利用者の文字列をそのまま返し、その戻り値に置換テンプレートの解釈は再び行われません。普通の検索・置換を約束するツールに適した方法です。単に文章を貼り付けるために、利用者がドル記号のエスケープを覚える必要はなくなります。

利用者の検索文字列から自動で正規表現を作って解決しようとしてはいけません。たとえば通常の文字列モードでのa.bは、任意の1文字ではなく、ピリオドそのものを探すべきです。正規表現のキャプチャや置換テンプレートも提供するなら、明確に表示した上級モードとして分けます。$1のようなテンプレートはそのモードでは有用なので、説明なしに単なる文字列へ変えてはいけません。

文字列の置換ではドル記号を解釈し、コールバックでは入力した文字をそのまま保持する
上の人工データを使ったNode.jsの例を正確に示す、筆者作成の比較図です。テキストエディターのスクリーンショットではありません。画像を開くと原寸で確認できます。
function replaceLiteralOnce(text, search, value) {
  return text.replace(search, () => value);
}
function replaceLiteralAll(text, search, value) {
  if (search === "") throw new Error("Search must not be empty");
  return text.replaceAll(search, () => value);
}

これらの関数は、アプリから渡される文字列を想定しています。一つは最初の一致、もう一つはすべての一致を置き換えます。空の検索文字列を拒否するのはreplaceLiteralAllだけで、コード単位の間への意図しない挿入を防ぎます。replaceLiteralOnceに空の検索文字列を渡すと、先頭に置換値が挿入されます。製品が意図的にキャプチャテンプレートを提供するなら、そのモードを残して明示し、黙って意味を変えないでください。

置換後の文章を最後まで読み比べる

特に[すべて置換]では、変更前と変更後の両方を見せましょう。ドル記号一つ、二つ、一致を表すトークン、空文字列を含む置換を試します。一致しない場合の動作も確認してください。空の置換文字列は正当な削除操作ですが、空の検索文字列は文中の各位置に文字を挿入し得るため、製品としての扱いを明確に決める必要があります。

最後に結果の表示方法を確認します。コールバックから文字列をそのまま返しても、HTMLが安全になるわけではありません。信頼できない文章のプレビューにはtextareaかtextContentを使い、貼り付けたタグを実行せず表示します。プレビューが利用者の意図と一致してから保存・送信し、一括編集には元に戻す手段を残してください。

記録された試験では、コールバックから返すことで$&、$'、$$、$1がそのまま保持されました。同様の例を自分の回帰テストにも追加し、繰り返し一致する場合と空の置換も含めましょう。元データを残し、一括編集はプレビューしてください。

記録結果:文字列引数では空になり、関数ではドル記号とアポストロフィがそのまま残る
既存の説明資料を保持しています。
人工的なJavaScript文字列置換テストの記録
ドル記号を含む文章のNode.js置換結果です。記録済みテスト出力のキャプチャであり、元の相談者のアプリ画面ではありません。検証画像を原寸で開く。

出典・関連資料