String.raw()

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

Спробуйте його в дії

Синтаксис

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 безпосередньо, як тег "ідентичності". Дивіться реалізацію такого коду в створенні тега ідентичності. Коли String.raw() викликається з об'єктом, чия властивість raw не має властивості length або має недодатне значення length, то повертається порожній рядок "". Якщо substitutions.length < strings.raw.length - 1 (тобто недостатньо замін для заповнення гнізд – що може трапитися з як слід сформованим шаблонним літералом), то решта гнізд заповнюється порожніми рядками.

Приклади

Застосування методу String.raw()

String.raw`Привіт\n${2 + 3}!`;
// 'Привіт\\n5!', символ після 'Привіт' насправді
//  не є символом початку рядка,
// '\' та 'n' — це два окремі символи.

String.raw`Привіт\u000A!`;
// 'Привіт\\u000A!', так само тут, цього разу ми отримуємо символи
//  \, u, 0, 0, 0, A, 6.
// Будь-які екрановані послідовності не працюватимуть, а
// зворотні косі риски опинятимуться у виведеному рядку.
// Можна це додатково підтвердити, перевіривши властивість .length
// рядка.

const name = "Вова";
String.raw`Привіт\n${name}!`;
// 'Привіт\\nВова!', вирази підставлення опрацьовано.

String.raw`Привіт \${name}!`;
// 'Привіт \\${name}!', знак долара екранований – інтерполяції немає.

Створення тега ідентичності

Чимало інструментів по-особливому обробляє літерали, теговані певним іменем.

// Частина форматувальників відформатує вміст цього літерала як HTML
const doc = html`<!doctype html>
  <html lang="uk">
    <head>
      <title>Привіт</title>
    </head>
    <body>
      <h1>Привіт, світе!</h1>
    </body>
  </html> `;

Хтось міг би наївно реалізувати тег html так:

const html = String.raw;

Що, фактично, спрацює в вищеописаному випадку. Проте у зв'язку з тим, що String.raw зчіплює докупи необроблені рядкові літерали, а не "зготовані", то послідовності екранування – не обробляються.

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

Це може бути не те, що потрібно в випадку тега "справжньої ідентичності", коли тег – це суто засіб розмітки, що не повинен змінювати значення літерала. У такому випадку можна створити власний тег і передати "зготований" (тобто з обробленими послідовностями екранування) літеральний масив у String.raw, удаючи, ніби то необроблені рядки.

const html = (strings, ...values) => String.raw({ raw: strings }, ...values);
// Частина форматувальників відформатує вміст цього літерала як HTML
const doc = html`<canvas> </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'

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

Специфікація
ECMAScript Language Specification (ECMAScript)
# sec-string.raw

Сумісність із браузерами

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
raw
Chrome Full support 41
 Edge Full support 12
 Firefox Full support 34
 Internet Explorer No support No
 Opera No support No
 Safari Full support 10
 WebView Android No support No
 Chrome Android Full support 41
 Firefox for Android Full support 34
 Opera Android No support No
 Safari on iOS Full support 10
 Samsung Internet Full support 4.0
 Deno Full support 1.0
 Node.js Full support 4.0.0

Дивіться також

Помітили помилку на цій сторінці?

Переглянути сирці на GitHub.

Редагувати вміст на GitHub.

Почати обговорення на GitHub стосовно вмісту цієї сторінки.