إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها
عرّف التعليقات التوضيحية مع سياسات الاحتفاظ وطبّقها على الأصناف والدوال والخصائص.
إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.
لماذا التعليقات التوضيحية المخصصة؟
التعليقات التوضيحية هي بيانات وصفية مرتبطة بالإعلانات، مثل الأصناف والدوال والخصائص والمعلمات. وتتيح لك التعليقات التوضيحية المخصصة تمييز الشيفرة لمعالجتها بواسطة الأطر أو أدوات البناء مثل KSP/KAPT، أو بواسطة منطقك الخاص في وقت التشغيل.
تعريف تعليق توضيحي
استخدم الكلمة المفتاحية annotation class. ويمكن لأصناف التعليقات التوضيحية أن تحتوي على معلمات منشئ، على أن تكون أنواعها مقتصرة على الأنواع البدائية أو String أو KClass أو التعدادات أو التعليقات التوضيحية الأخرى أو مصفوفات من هذه الأنواع:
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)التعليقات التوضيحية الوصفية: @Target
يقيّد @Target المواضع التي يمكن استخدام التعليق التوضيحي فيها. ومن الأهداف الشائعة: CLASS وFUNCTION وPROPERTY وFIELD وVALUE_PARAMETER وCONSTRUCTOR.
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)@Retention: متى يتوفر التعليق التوضيحي؟
يتحكم @Retention في مدة بقاء التعليق التوضيحي:
SOURCE— يُتخلّص منه بعد الترجمةBINARY— يُخزَّن في ملف .class لكنه لا يظهر عبر الانعكاسRUNTIME— يُخزَّن ويظهر في وقت التشغيل، وهو الافتراضي في معظم حالات الاستخدام
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)@Repeatable: تطبيق التعليق التوضيحي نفسه عدة مرات
لا يمكن تطبيق التعليق التوضيحي أكثر من مرة على الإعلان الواحد افتراضيًا. استخدم @Repeatable للسماح بتطبيقه عدة مرات:
@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)إضافة التعليقات التوضيحية إلى المنشئات والمعلمات
يمكنك إضافة تعليقات توضيحية إلى معلمات المنشئ وخصائص المنشئ الأساسي. استخدم أهداف موضع الاستخدام @field: أو @get: أو @param: للتحكم في العنصر الذي يتلقى التعليق التوضيحي:
data class User(
@field:Validate(minLength = 2) val name: String,
@field:Validate(minLength = 0, maxLength = 120) val email: String
)أهداف موضع الاستخدام
تنشئ Kotlin عدة عناصر في الشيفرة الثنائية من خاصية واحدة، مثل الحقل وgetter وsetter والمعلمة. وتحدد أهداف موضع الاستخدام العنصر الذي يتلقى التعليق التوضيحي:
@field:الحقل الداعم@get:دالة getter@set:دالة setter@param:معلمة المنشئ
إضافة التعليقات التوضيحية إلى الأصناف
تفيد التعليقات التوضيحية على الصنف في تمييزه لمعالجة الأطر، مثل تمييز الصنف باعتباره قابلًا للتسلسل أو قابلًا للحقن أو جزءًا من وحدة معينة:
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository
@Repository
class UserRepository@MustBeDocumented
يضمن إضافة @MustBeDocumented ظهور التعليق التوضيحي في توثيق واجهة برمجة التطبيقات المُنشأ. استخدمه للتعليقات التوضيحية التي تشكل جزءًا من عقد واجهة برمجة التطبيقات العامة.
@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)معلمات التعليقات التوضيحية: القيم الافتراضية والمصفوفات
يمكن أن تكون للمعلمات قيم افتراضية، ويمكنها قبول المصفوفات باستخدام الكلمة المفتاحية vararg أو أنواع المصفوفات الصريحة:
annotation class Roles(vararg val value: String)
@Roles("ADMIN", "EDITOR")
class AdminPanelمعلمات KClass في التعليقات التوضيحية
يمكن للتعليقات التوضيحية الإشارة إلى أنواع الأصناف عبر KClass:
annotation class Serializer(val using: KClass<out Any>)
@Serializer(using = GsonAdapter::class)
class Eventتحقق سريع
أي قيمة من @Retention تجعل التعليق التوضيحي المخصص متاحًا عبر انعكاس Kotlin في وقت التشغيل؟
مراجعة: التعليقات التوضيحية المخصصة
أهم النقاط:
- يُعرَّف باستخدام
annotation class؛ وتقتصر المعلمات على الأنواع البدائية وString وKClass والتعدادات والمصفوفات @Target— المواضع التي يمكن تطبيقه فيها@Retention— وقت توفره، فاستخدم RUNTIME للانعكاس@Repeatable— يسمح بتطبيقه عدة مرات على إعلان واحد- تتحكم أهداف موضع الاستخدام، مثل
@field:و@get:، في عنصر الشيفرة الثنائية الذي يتلقى التعليق التوضيحي
تعلم Kotlin مع معلم ذكاء اصطناعي — مجانًا
اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.
- الدورات
- 51
- الدروس
- 203
الأسئلة الشائعة
هل درس «إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها» مجاني؟
نعم — نص درس «إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.
ماذا ستتعلم في «إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها»؟
عرّف التعليقات التوضيحية مع سياسات الاحتفاظ وطبّقها على الأصناف والدوال والخصائص. تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟
لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.
كم من الوقت يستغرق درس «إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟
نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- انعكاس Kotlin: KClass وKFunction وKProperty
- إنشاء التعليقات التوضيحية المخصصة وتحديد أهدافها
- قراءة التعليقات التوضيحية وقت التشغيل
- التحقق والتعيين المعتمدان على الانعكاس