String.raw()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年9月.

String.raw() 静的メソッドは、テンプレートリテラルのためのタグ関数です。この関数は Python の文字列リテラルの r 接頭辞や C# の文字列リテラルの @ 接頭辞に似ています。この関数は、テンプレートリテラルの生の文字列形式を取得するために使用されます。つまり、置換（${foo} など）は行われますが、エスケープ（\n など）は実行されません。

試してみましょう

// バックスラッシュをエスケープせずに Windows パスを使用する変数を作成
const filePath = String.raw`C:\Development\profile\about.html`;

console.log(`The file was uploaded from: ${filePath}`);
// 予想される結果: "The file was uploaded from: C:\Development\profile\about.html"

構文

js
String.raw(strings)
String.raw(strings, sub1)
String.raw(strings, sub1, sub2)
String.raw(strings, sub1, sub2, /* …, */ subN)

String.raw`templateString`

引数

strings

整形式のテンプレートリテラル配列オブジェクト、たとえば { raw: ['foo', 'bar', 'baz'] } などです。文字列の配列風オブジェクトを値として持つ raw プロパティを持っているオブジェクトであるべきです。

sub1, …, subN

置換される値が入ります。

templateString

テンプレートリテラルです。オプションで置換文字列 (${...}) を含みます。

例外

TypeError

第 1 引数に raw プロパティが含まれていなかったり、raw プロパティが undefined または null 出会ったりした場合に発生します。

解説

ほとんどの場合、String.raw() はテンプレートリテラルとともに使用されます。前述の最初の構文は、滅多に使用されません。JavaScript エンジンが（他のタグ関数のように）適切な引数で呼び出すからです。

String.raw() はテンプレートリテラルの唯一の組み込みタグ関数です。既定のテンプレート関数のように動作し、連結を行います。通常の JavaScript コードで再実装することができます。

警告: String.raw を直接「識別」タグとして使用しないでください。この実装方法については識別タグの構築を参照してください。

String.raw() が raw プロパティに length プロパティがないか、正でない length を持つオブジェクトで呼び出された場合、空の文字列 "" を返します。もし substitutions.length < strings.raw.length - 1 （つまり、プレースホルダーを埋めるだけの置換がない - 整形式タグ付きテンプレートリテラルでは起こりえない）場合、残りのプレースホルダーは空の文字列で埋められます。

例

String.raw() の使用

js
String.raw`Hi\n${2 + 3}!`;
// 'Hi\\n5!' です。'Hi' の次の文字は
// 改行文字ではなく、
// '\' および 'n' は 2 つの文字です。

String.raw`Hi\u000A!`;
// 'Hi\\u000A!' です。同様で、今回は
// \, u, 0, 0, 0, A, の 6 文字です。
// すべての種類のエスケープ文字は無効で、バックスラッシュが
// 出力文字列中に存在します。
// 文字列の .length プロパティを調べると確認できます。

const name = "Bob";
String.raw`Hi\n${name}!`;
// 'Hi\\nBob!' です。置き換えが処理されます。

String.raw`Hi \${name}!`;
// 'Hi \\${name}!' です。ドル記号がエスケープされます。補間は行われません。

String.raw と RegExp の使用

String.raw テンプレートリテラルと RegExp() コンストラクターを組み合わせることで、次のことが可能になります。正規表現リテラルでは使用できない、動的な部分を含む正規表現を作成する正規表現のエスケープシーケンスを二重エスケープ (\\) する必要がありません（通常の文字列リテラルでは使用できません）。これは、ファイルパスや URL など、スラッシュが多く含まれている文字列でも役立ちます。

js
// String.raw テンプレートを使用すると、 URL と照合する、かなり読み取り可能な正規表現を作成できる
const reRawTemplate = new RegExp(
  String.raw`https://developer\.mozilla\.org/en-US/docs/Web/JavaScript/Reference/`,
);

// 正規表現リテラルで同じことを見ていくと、それぞれのフォワードスラッシュは
// \/ で置き換えられます。
const reRegexpLiteral =
  /https:\/\/developer\.mozilla\.org\/en-US\/docs\/Web\/JavaScript\/Reference\//;

// RegExp コンストラクターと、各ピリオドに \\. を使用した従来の文字列リテラルで
// 同じことを記述すると、次のようになります。
const reStringLiteral = new RegExp(
  "https://developer\\.mozilla\\.org/en-US/docs/Web/JavaScript/Reference/",
);

// String.raw では、動的な部分も含むことができる
function makeURLRegExp(path) {
  return new RegExp(String.raw`https://developer\.mozilla\.org/${path}`);
}

const reDynamic = makeURLRegExp("en-US/docs/Web/JavaScript/Reference/");
const reWildcard = makeURLRegExp(".*");

識別タグの構築

多くのツールは、特定の名前でタグ付けされたリテラルを特別扱いします。

js
// フォーマッターによっては、このリテラルのコンテンツを HTML として書式化する
const doc = html`<!doctype html>
  <html lang="en-US">
    <head>
      <title>Hello</title>
    </head>
    <body>
      <h1>Hello world!</h1>
    </body>
  </html>`;

html タグを素朴に実装するためには、次のようにします。

const html = String.raw;

これは、実際は、上記のように動作します。しかし、String.raw は "cooked" 文字列ではなく、生の文字列リテラルを連結するので、エスケープシーケンスは処理されません。

js
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\\n</canvas>"

タグが純粋にマークアップのためのもので、リテラルの値を変更しないような「純粋な識別タグ」では、これは望むものではないかもしれません。この場合、カスタムタグを作成し、"cooked"（つまり、エスケープシーケンスが処理されたｓ）リテラル配列を String.raw に渡して、生の文字列であるかのように見せかけることができます。

js
const html = (strings, ...values) => String.raw({ raw: strings }, ...values);
// フォーマッターによっては、このリテラルのコンテンツを HTML として書式化する
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\n</canvas>"; "\n" が改行文字になる

最初の引数は raw プロパティを持つオブジェクトで、その値はテンプレートリテラルの区切られた文字列を表す配列風オブジェクト（length プロパティと整数のインデックスを持つ）であることに注意してください。残りの引数は置き換え用です。raw の値は配列風オブジェクトであれば何でも良いので、文字列であっても構いません。例えば、 'test' は ['t', 'e', 's', 't'] として扱われます。以下は `t${0}e${1}s${2}t` と等価です。

String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t'