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 September 2015.

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

試してみましょう

構文

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}!' です。ドル記号がエスケープされます。補間は行われません。

識別タグの構築

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

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

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

js
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` と等価です。

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

仕様書

Specification
ECMAScript Language Specification
# sec-string.raw

ブラウザーの互換性

BCD tables only load in the browser

関連情報