أنواع Template Literal في TypeScript: الصياغة والأمثلة

نوع template literal يبني أنواعًا حرفية نصية بصياغة علامات backtick نفسها المستخدمة في قوالب النصوص في JavaScript. فالنوع `on${Capitalize<"click" | "focus">}` هو "onClick" | "onFocus"، ويحسبه المترجم:

type DomEvent = "click" | "focus" | "blur";

type HandlerName = `on${Capitalize<DomEvent>}`;
// "onClick" | "onFocus" | "onBlur"

const handlers: Record<HandlerName, () => string> = {
  onClick: () => "clicked",
  onFocus: () => "focused",
  onBlur: () => "blurred",
};

console.log(handlers.onFocus()); // focused
// @ts-expect-error: "onHover" is not one of the handler names
handlers.onHover;

أنواع template literal موجودة وقت الترجمة فقط. تفحص الأنواع الحرفية النصية والقيم ذات الأنواع المعروفة أثناء كتابة الكود، ولا تضيف شيئًا إلى مخرجات JavaScript. يستخدم جدول المعالجات أعلاه Record ليشترط دالة واحدة لكل اسم.

الصياغة

داخل علامات backtick تكتب نصًا حرفيًا وعناصر نائبة ${...}. يحمل العنصر النائب نوعًا لا قيمة: نوعًا حرفيًا من string أو number أو bigint أو boolean، أو union منها، أو أحد الأنواع الواسعة string وnumber وbigint وboolean وnull وundefined.

type Greeting = `hello ${string}`;   // any string that starts with "hello "
type Version = `v${number}`;         // "v1", "v2.5", ...
type Toggle = `is-${boolean}`;       // "is-true" | "is-false"

const g: Greeting = "hello Ada";
const v: Version = "v3";
const t: Toggle = "is-false";

// @ts-expect-error: Type '"hi Ada"' is not assignable to type '`hello ${string}`'
const wrong: Greeting = "hi Ada";

console.log(g, v, t); // hello Ada v3 is-false

العنصر النائب ذو النوع الواسع مثل string أو number يصنع نمطًا: يبقى النوع `hello ${string}` ويُقبل أي نص يطابقه. أما العنصر النائب ذو union المحدود، مثل boolean، فيُوسَّع إلى أعضائه.

أعضاء union تتضاعف

مع عدة unions تكون النتيجة كل التركيبات:

type Size = "sm" | "md" | "lg";
type Tone = "primary" | "danger";

type ButtonClass = `btn-${Size}-${Tone}`;
// "btn-sm-primary" | "btn-sm-danger" | "btn-md-primary" | ... (6 members)

function button(cls: ButtonClass): string {
  return `<button class="${cls}">`;
}

console.log(button("btn-lg-danger")); // <button class="btn-lg-danger">
// button("btn-xl-danger") would be error TS2345

ثلاثة أحجام في درجتين لونيتين تعطي ستة أعضاء. ويكبر العدد بسرعة: خمسة عناصر نائبة يحمل كل منها union من عشرة أحرف تعطي 100,000 عضو، وترفض TypeScript ذلك بالخطأ error TS2590: Expression produces a union type that is too complex to represent. استخدم عنصرًا نائبًا واسعًا مثل ${string} عندما لا تحتاج إلى كل قيمة بعينها.

Uppercase وLowercase وCapitalize وUncapitalize

أربعة أنواع مدمجة تغيّر حالة الأحرف في الأنواع الحرفية النصية. إنها أنواع جوهرية (intrinsic): منفذة داخل المترجم، وليست مكتوبة بـ TypeScript.

إنها تغيّر الأنواع فقط. لبناء النص المقابل وقت التشغيل ما زلت تستدعي toUpperCase() أو تقتطع النص وتكبّر الحرف الأول بنفسك، ثم تخبر TypeScript أن للنتيجة النوع الدقيق:

function capitalize<S extends string>(s: S): Capitalize<S> {
  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
}

const title = capitalize("report"); // type "Report"
const loud: Uppercase<"ok"> = "OK";

console.log(title, loud); // Report OK

الـ as ضروري لأن نوع القيمة المُعادة من toUpperCase() هو string العادي. توقيع الدالة هو ما يراه المستدعون، لذا فلـ capitalize("report") النوع الحرفي "Report".

أنماط النصوص: ${number}px وأخواتها

يقبل نوع النمط كل نص له شكل معيّن. وهو مفيد لقيم CSS والمعرّفات والمفاتيح ذات البادئة المعروفة:

type Pixels = `${number}px`;
type UserId = `user_${string}`;
type Semver = `${number}.${number}.${number}`;

function setWidth(w: Pixels) {
  return `width: ${w}`;
}

const id: UserId = "user_42";
const version: Semver = "7.0.2";

console.log(setWidth("120px"), id, version); // width: 120px user_42 7.0.2
// setWidth("120") and setWidth("wide px") would both be error TS2345

يقبل ${number} أي نص تقرؤه JavaScript كرقم، وهذا أوسع مما يبدو: "-3px" و"1e3px" و"0x10px" كلها تجتاز فحص الأنواع. تعامل مع هذه الأنماط كحماية من الأخطاء الإملائية في القيم الحرفية، لا كتحقق كامل.

أنواع template literal مع mapped types

أنواع template literal أكثر فائدة في جملة as من mapped type، حيث تولّد أسماء خصائص من أسماء خصائص أخرى:

type Watchers<T> = {
  [K in keyof T as `on${Capitalize<string & K>}Change`]: (value: T[K]) => void;
};

type Form = { email: string; age: number };

// { onEmailChange: (value: string) => void; onAgeChange: (value: number) => void }
const watch: Watchers<Form> = {
  onEmailChange: (v) => console.log("email is now", v),
  onAgeChange: (v) => console.log("age is now", v.toFixed(0)), // v is number
};

watch.onEmailChange("ada@example.com"); // email is now ada@example.com
watch.onAgeChange(37);                  // age is now 37

يُبقي string & K المفاتيح النصية فقط، لأن Capitalize لا يقبل الأرقام ولا الرموز (symbols). وتأخذ كل دالة رد نداء نوع معاملها من الخاصية التي تراقبها.

تحليل النصوص بـ infer

في النوع الشرطي، يمكن لـ template literal أن يطابق نصًا ويلتقط أجزاء منه بـ infer. هذا المثال يستخرج أسماء المعاملات من نمط مسار:

type RouteParams<S extends string> =
  S extends `${string}:${infer Param}/${infer Rest}`
    ? Param | RouteParams<`/${Rest}`>
    : S extends `${string}:${infer Param}`
      ? Param
      : never;

type P = RouteParams<"/users/:userId/posts/:postId">; // "userId" | "postId"

function link<S extends string>(pattern: S, params: Record<RouteParams<S>, string>): string {
  return pattern.replace(/:(\w+)/g, (_, key: string) => params[key as RouteParams<S>]);
}

console.log(link("/users/:userId/posts/:postId", { userId: "7", postId: "42" }));
// /users/7/posts/42

احذف postId من الاستدعاء وسيبلّغ المترجم أنه مفقود.

تعبيرات القوالب تتوسع إلى string

تعبير قالب النص في الكود العادي نوعه string، حتى عندما يكون كل جزء منه نوعًا حرفيًا. أضف as const لتحتفظ بنوع template literal:

type Level = "info" | "warn";

function tag(level: Level) {
  const loose = `log:${level}`;          // string
  const exact = `log:${level}` as const; // "log:info" | "log:warn"
  return { loose, exact };
}

const { exact } = tag("warn");
const again: `log:${Level}` = exact; // OK: the exact type fits
console.log(exact, again);           // log:warn log:warn

بدون as const يفشل إسناد loose إلى `log:${Level}`، لأن string قد يكون أي شيء.