String.raw()‎

الدالة String.raw()‎ هي دالة وسم (tag function) للقوالب template literals، شبيهة بالسابقة r في لغة Python أو السابقة @ في C#‎ (لكن هنالك اختلافات بينهما). وتُستخدَم للحصول على السلسلة النصية الخام من القالب (أي النص غير المُفسَّر).

البنية العامة

String.raw(callSite, ...substitutions)

String.raw`templateString`

callSite

كائن لاستدعاء القالب مثل: ‎‎{ raw: ['foo', 'bar', 'baz'] }‎.

‎...substitutions

القيم التي ستُستبدل.

templateString

سلسلة نصية تُمثِّل القالب، ويمكن وجود القيم التي ستُستبدَل فيها (‎${...}‎).

القيمة المعادة

سلسلة نصية خام للسلسلة النصية التي تُمثِّل القالب.

الاستثناءات

سيرمى الاستثناء TypeError إذا كان أوّل وسيط ليس كائنًا مُعرَّفًا بشكلٍ صحيح.

الوصف

في أغلبية الحالات، تُستخدَم الدالة String.raw()‎ مع السلاسل النصية التي تُمثِّل القوالب. وأوّل شكل مذكور أعلاه لا يُستخدَم إلا نادرًا؛ وذلك لأنَّ مُحرِّك JavaScript سيستدعي هذا الشكل مع الوسائط اللازمة تلقائيًا.

أمثلة

الأمثلة الآتية تُبيّن استخدام الدالة 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.

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

// Normally you would not call String.raw() as a function,
// but to simulate `t${0}e${1}s${2}t` you can do:
String.raw({ raw: 'test' }, 0, 1, 2); // 't0e1s2t'
// Note that 'test', a string, is an array-like object
// The following is equivalent to
// `foo${2 + 3}bar${'Java' + 'Script'}baz`
String.raw({
  raw: ['foo', 'bar', 'baz'] 
}, 2 + 3, 'Java' + 'Script'); // 'foo5barJavaScriptbaz'

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	41	34	غير مدعومة	غير مدعومة	10

على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.