TypeScript Academy · درس

بيانات Decorator الوصفية

أرفقوا البيانات الوصفية واقرؤوها باستخدام metadata API

بيانات Decorator الوصفية درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

واجهة برمجة تطبيقات البيانات الوصفية لـ Decorator

تتضمن Decorators المعيارية قناة metadata مضمّنة. ويعرِض كائن السياق كائن metadata يمكنكم الكتابة إليه، ثم تحمل الفئة هذه البيانات لاحقًا تحت المفتاح المعروف Symbol.metadata.

context.metadata

يشترك سياق كل مزخرف في كائن واحد من metadata للفئة التي يجري تعريفها. وتُرفق المزخرفات البيانات به، لتصبح في النهاية البيانات الوصفية للفئة.

function tag(label: string) {
  return function (value: any, context: DecoratorContext) {
    context.metadata[context.name] = label;
  };
}

القراءة عبر Symbol.metadata

بعد تعريف الفئة، تصبح البيانات الوصفية المجمعة متاحة عبر SomeClass[Symbol.metadata].

class User {
  @tag("identifier") id = 0;
  @tag("display")    name = "";
}

const meta = (User as any)[Symbol.metadata];
console.log(meta); // { id: "identifier", name: "display" }

لماذا نستخدم كائنًا مشتركًا

بما أن جميع المزخرفات الموجودة في الفئة تكتب في كائن metadata نفسه، يمكنكم تجميع المعلومات من مزخرفات متعددة في سجل واحد متماسك يصف الفئة.

تخزين بيانات وصفية منظمة

يمكن أن تكون قيم البيانات الوصفية بأي بنية. ومن الأنماط الشائعة الاحتفاظ بسجل متداخل تكون مفاتيحه أسماء الأعضاء.

function column(type: string) {
  return function (value: any, context: ClassFieldDecoratorContext) {
    const md = context.metadata as any;
    md.columns ??= {};
    md.columns[context.name] = { type };
  };
}

البيانات الوصفية على مستوى الفئة

يمكن لمزخرف الفئة أيضًا كتابة بيانات وصفية، مثل اسم جدول يكمل معلومات الأعمدة الخاصة بكل حقل.

function entity(table: string) {
  return function (value: Function, context: ClassDecoratorContext) {
    (context.metadata as any).table = table;
  };
}

@entity("users")
class UserEntity {
  @column("serial") id = 0;
  @column("text")   name = "";
}

توريث البيانات الوصفية

ترتبط كائنات البيانات الوصفية على امتداد سلسلة النموذج الأولي: إذ يكون كائن البيانات الوصفية للفئة الفرعية ذا بيانات الفئة الأصلية كنموذج أولي له، ولذلك تظهر الإدخالات الموروثة ما لم تُستبدل.

Polyfill لـ Symbol.metadata

يُعد Symbol.metadata رمزًا معروفًا. وفي البيئات التي لا توفره، تُسنِدون polyfill إليه حتى يتمكن وقت التشغيل من إرفاق الكائن المجمّع.

(Symbol as any).metadata ??= Symbol.for("Symbol.metadata");

البيانات الوصفية دون reflect-metadata

تُعد واجهة برمجة التطبيقات هذه جزءًا من اقتراح المزخرفات نفسه، ولذلك فهي لا تتطلب مكتبة reflect-metadata المنفصلة. وتظل تلك المكتبة مهمة فقط لإصدار نوع التصميم التجريبي الأقدم (في الدرس التالي).

مساعد عملي للقراءة

يوحّد موصّل وصول صغير قراءة البيانات الوصفية من أي فئة، ويُرجع كائنًا فارغًا عند عدم وجودها.

function getMeta(cls: any): Record<string, any> {
  return (cls[Symbol.metadata] as Record<string, any>) ?? {};
}

لماذا يهم ذلك

تحوّل البيانات الوصفية المزخرفات من أغلفة سلوك تُستخدم لمرة واحدة إلى وصف تصريحي لفئاتكم. وتقرأ الأطر هذا الوصف لإنشاء ORM وأدوات التحقق وأجهزة التوجيه دون اللجوء إلى حيل الانعكاس وقت التشغيل.

اختبار سريع

تأكدوا من فهمكم لواجهة برمجة تطبيقات البيانات الوصفية.

مراجعة

تمنح واجهة برمجة تطبيقات البيانات الوصفية للمزخرفات كل مزخرف كائن context.metadata مشتركًا، وتتيحه على الفئة عبر Symbol.metadata. وتجمع المزخرفات بيانات وصفية منظمة قابلة للتوريث دون مكتبة خارجية، مما يتيح أوصافًا تصريحية للفئات ملائمة للأطر.

الأسئلة الشائعة

هل درس «بيانات Decorator الوصفية» مجاني؟

نعم — نص درس «بيانات Decorator الوصفية» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «بيانات Decorator الوصفية»؟

أرفقوا البيانات الوصفية واقرؤوها باستخدام metadata API تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «بيانات Decorator الوصفية»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى TypeScript Academy