كتابة التعليقات التوضيحية المخصصة
إرفاق البيانات الوصفية بتصريحاتكم
كتابة التعليقات التوضيحية المخصصة درس مجاني في Dart Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Dart Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Dart Academy 4 دروس في المجموع.
التعليقات التوضيحية هي أصناف
إن annotation المخصصة مجرد صنف عادي. فعندما تكتبون @MyTag، فإنكم تشيرون إلى نسخة من ذلك الصنف بوصفها بيانات وصفية. 🏷️
عرّفوا الصنف
ابدؤوا بتعريف صنف عادي لحفظ بياناتكم الوصفية. في هذا المثال، ستحمل annotation بسيطة باسم Todo رسالةً ومالكًا لاحقًا.
class Todo {
final String message;
const Todo(this.message);
}قاعدة المنشئ const
يجب أن تكون قيم التعليقات التوضيحية ثوابت وقت الترجمة، لذلك يجب أن يكون المنشئ const. ومن دونه لا يمكنكم استخدام الصنف بوصفه annotation.
طبّقوا annotation الخاصة بكم
استخدموا البادئة @ مع إنشاء const. يوثّق وسم @Todo هذا العمل الذي لا يزال يتطلب التنفيذ في الطريقة التالية.
@Todo('Add validation')
void saveForm() {}احملوا حقولًا متعددة
يمكن أن تحتوي annotation الخاصة بكم على أي عدد تريدونه من fields. امنحوا المنشئ وسائط مسماة عندما تريدون وسومًا أوضح وتصف نفسها بنفسها.
class Todo {
final String task;
final String who;
const Todo(this.task, this.who);
}الوسائط الثابتة فقط
يجب أن تكون كل وسيطة تمررونها constant بحد ذاتها. تصلح القيم الحرفية والكائنات من نوع const وقيم enum، أما متغير وقت التشغيل فلا يصلح.
وسم بلا وسائط
أحيانًا لا تحتاجون إلا إلى علامة. تعمل نسخة const بلا بيانات بوصفها marker خالصًا ترفقونه بالتصريحات.
class Experimental {
const Experimental();
}
const experimental = Experimental();ثوابت const الصغيرة المريحة
يتيح كشف نسخة const بأحرف صغيرة للمستدعين كتابة @experimental بطريقة نظيفة بدلًا من @Experimental() في كل مرة.
@experimental
void betaFeature() {}لا تفعل شيئًا بمفردها
مثل التعليقات التوضيحية المضمّنة، لا تملك annotation المخصصة أي سلوك بحد ذاتها. يجب أن يقرأها شيء ما حتى تصبح مفيدة، وسنتناول ذلك لاحقًا.
من يقرأ التعليقات التوضيحية؟
هناك قارئان مهمان: مولدات الكود في وقت الإنشاء، وأدوات شبيهة بالانعكاس. يفحص كلاهما وسومكم ويتصرف بناءً على البيانات الوصفية التي يعثر عليها.
حافظوا على صغر التعليقات التوضيحية
تبقى التعليقات التوضيحية الجيدة صغيرة وتصريحية. خزّنوا بيانات بسيطة لا منطقًا برمجيًا، حتى تتمكن أي أداة من قراءتها بطريقة متوقعة وآمنة.
تحقق سريع
ما الذي يجب أن يحتوي عليه الصنف حتى يمكن استخدامه بوصفه annotation؟
مراجعة
الـ annotation المخصصة صنف له منشئ const. طبّقوها باستخدام @، ومرروا وسائط ثابتة، ودعوا الأدوات تقرأ البيانات الوصفية لاحقًا. 🎉
الأسئلة الشائعة
هل درس «كتابة التعليقات التوضيحية المخصصة» مجاني؟
نعم — نص درس «كتابة التعليقات التوضيحية المخصصة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Dart Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Dart Academy 4 دروس في المجموع.
ماذا ستتعلم في «كتابة التعليقات التوضيحية المخصصة»؟
إرفاق البيانات الوصفية بتصريحاتكم تتمرن على Dart Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Dart Academy؟
لا تُشترط خبرة سابقة. Dart Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.
كم من الوقت يستغرق درس «كتابة التعليقات التوضيحية المخصصة»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Dart Academy هذا؟
نعم. كل درس في Dart Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- التعليقات التوضيحية المضمّنة: override وdeprecated
- كتابة التعليقات التوضيحية المخصصة
- توليد الشيفرة باستخدام build_runner
- json_serializable عمليًا