String.raw()

Статический метод String.raw() является теговой функцией для шаблонных литералов. Это похоже на префикс r в Python или префикс @ в C# для строковых литералов. Он используется для получения необработанной (сырой) строковой формы шаблонных литералов — то есть, подстановки (например, ${foo}) обрабатываются, но escape-последовательности (например, \n) — нет.

Попробовать

// Create a variable that uses a Windows
// path without escaping the backslashes:
const filePath = String.raw`C:\Development\profile\about.html`;

console.log(`The file was uploaded from: ${filePath}`);
// Expected output: "The file was uploaded from: C:\Development\profile\about.html"

Синтаксис

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

Выдается, если первый аргумент не имеет свойства raw, или если свойство raw равно undefined или null.

Описание

В большинстве случаев String.raw() используется с шаблонными литералами. Первый синтаксис, упомянутый выше, используется редко, потому что движок JavaScript вызовет его с правильными аргументами автоматически (так же, как и другие тег-функции).

String.raw() — это единственный встроенный тег шаблонного литерала. Он близок по семантике к нетегированному литералу, поскольку он конкатенирует все аргументы и возвращает строку. Вы даже можете повторно реализовать его с помощью обычного кода JavaScript.

Если String.raw() вызывается с объектом, свойство raw которого не имеет свойства length или имеет неположительное значение length, он возвращает пустую строку "". Если substitutions.length < strings.raw.length - 1 (т. е. недостаточно подстановок для заполнения заполнителей — что невозможно в правильно сформированном тегированном шаблонном литерале), остальные заполнители заполняются пустыми строками.

Примеры

Использование String.raw()

String.raw`Hi\n${2 + 3}!`;
// 'Hi\\n5!', the character after 'Hi'
// is not a newline character,
// '\' and 'n' are two characters.

String.raw`Hi\u000A!`;
// 'Hi\\u000A!', same here, this time we will get the
// \, u, 0, 0, 0, A, 6 characters.
// All kinds of escape characters will be ineffective
// and backslashes will be present in the output string.
// You can confirm this by checking the .length property
// of the string.

const name = "Bob";
String.raw`Hi\n${name}!`;
// 'Hi\\nBob!', substitutions are processed.

Необработанные строки, содержащие синтаксис шаблонных литералов

String.raw — это функция, поэтому она не может обойти базовый синтаксис шаблонных литералов, такой как обратные кавычки в качестве разделителей и ${ для подстановок. Если вы хотите включить эти символы в выходную строку, вам нужно экранировать их обратными слэшами. Однако, поскольку String.raw выводит необработанные строки, обратные слэши будут сохранены в выводе.

String.raw`Hi \${name}!`;
// 'Hi \\${name}!', the dollar sign is escaped; there's no interpolation.
// However, the backslash is still present in the output string.

String.raw`This is a backtick: \``;
// 'This is a backtick: \\`', the backslash is still present.

String.raw`A trailing backslash: \\`;
// 'A trailing backslash: \\\\', both backslashes are present.
// If you use a single backslash at the end, it escapes the ending backtick,
// causing subsequent code to be included in the string.

Чтобы обойти это, вы можете использовать подстановку для вставки этих символов.

String.raw`Hi ${"$"}{name}!`;
// 'Hi ${name}!', the substitution inserts a single dollar sign.
String.raw`This is a backtick: ${"`"}`;
// 'This is a backtick: `', the substitution inserts a single backtick.
String.raw`A trailing backslash: ${"\\"}`;
// 'A trailing backslash: \\', the substitution inserts a single backslash.

Этот подход работает для String.raw, потому что он просто конкатенирует необработанные строки и подстановки. К сожалению, в целом, тег шаблонного литерала не может получить строку raw, которая содержит неэкранированный синтаксис шаблонного литерала.

function tag(strings) {
  console.log(strings.raw[0]); // This will never contain unescaped `${` or backticks
}

Использование String.raw с RegExp

Сочетание шаблонного литерала String.raw с конструктором RegExp() позволяет создавать регулярные выражения с динамическими частями (что невозможно с литералами регулярных выражений) без двойного экранирования (\\) escape-последовательностей регулярных выражений (что невозможно с обычными строковыми литералами). Это также полезно для строк, содержащих много слэшей, таких как пути к файлам или URL-адреса.

// A String.raw template allows a fairly readable regular expression matching a URL:
const reRawTemplate = new RegExp(
  String.raw`https://developer\.mozilla\.org/en-US/docs/Web/JavaScript/Reference/`,
);

// The same thing with a regexp literal looks like this, with \/ for
// each forward slash:
const reRegexpLiteral =
  /https:\/\/developer\.mozilla\.org\/en-US\/docs\/Web\/JavaScript\/Reference\//;

// And the same thing written with the RegExp constructor and a
// traditional string literal, with \\. for each period:
const reStringLiteral = new RegExp(
  "https://developer\\.mozilla\\.org/en-US/docs/Web/JavaScript/Reference/",
);

// String.raw also allows dynamic parts to be included
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(".*");

Создание тега идентичности

Многие инструменты применяют специальную обработку к литералам, помеченным определенным именем.

// Some formatters will format this literal's content as 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 конкатенирует необработанные строковые литералы вместо «приготовленных», escape-последовательности не будут обработаны.

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

Возможно, это не то, что вам нужно для тега «истинной идентичности», где тег предназначен исключительно для разметки и не меняет значение литерала. В этом случае вы можете создать собственный тег и передать массив «приготовленных» литералов (т. е. обработанных escape-последовательностей) в String.raw, притворяясь, что это необработанные строки.

const html = (strings, ...values) => String.raw({ raw: strings }, ...values);
// Some formatters will format this literal's content as HTML
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\n</canvas>"; the "\n" becomes a line break

Обратите внимание, что первый аргумент — это объект со свойством raw, значение которого представляет собой массивоподобный объект (со свойством length и целочисленными индексами), представляющий разделенные строки в шаблонном литерале. Остальные аргументы — это подстановки. Поскольку значение raw может быть любым массивоподобным объектом, оно может быть даже строкой! Например, 'test' обрабатывается как ['t', 'e', 's', 't']. Следующее эквивалентно `t${0}e${1}s${2}t`:

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

Спецификации

Совместимость с браузерами

Смотрите также

• Полифилл String.raw в core-js
• Полифилл es-shims для String.raw
• Шаблонные литералы
• String
• Лексическая грамматика