Kotlin Academy · درس

تعريف Annotations

أنشئوا Annotations مخصصة

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

تعريف تعليمة توضيحية

تعرّف تعليمة توضيحية باستخدام الكلمتين annotation class. أبسط التعليقات التوضيحية لا تحمل أي بيانات وتعمل كعلامة.

annotation class Beta

@Beta
fun newFeature() = "experimental"

fun main() {
    println(newFeature())
}

معاملات التعليقات التوضيحية

يمكن أن تحمل التعليقات التوضيحية بيانات من خلال معاملات المُنشئ. والأنواع المسموح بها محدودة: الأنواع البدائية، وString، والتعدادات، والتعليقات التوضيحية الأخرى، وKClass، والمصفوفات من هذه الأنواع.

annotation class ApiVersion(val value: Int)

@ApiVersion(2)
fun endpoint() = "v2"

fun main() {
    println(endpoint())
}

@Target

تقيّد @Target المواضع التي يمكن تطبيق تعليمتك التوضيحية فيها. وتمرر إليها قيمة واحدة أو أكثر من قيم AnnotationTarget، مثل CLASS أو FUNCTION أو PROPERTY.

@Target(AnnotationTarget.FUNCTION)
annotation class Loggable

@Loggable
fun process() = "processing"

fun main() {
    println(process())
}

@Retention

تتحكم @Retention في المدة التي تبقى خلالها التعليمة التوضيحية:

SOURCE — يتخلص منها المترجم
BINARY — تبقى في ملف الفئة، لكنها لا تكون مرئية للانعكاس
RUNTIME — تبقى وتكون مرئية للانعكاس، وهي القيمة الافتراضية

@Retention(AnnotationRetention.RUNTIME)
annotation class Important

@Important
class Order

fun main() {
    println("Important is readable at runtime")
}

أهداف متعددة

أدرج عدة أهداف للسماح باستخدام التعليمة التوضيحية في أكثر من موضع. في هذه الحالة، تعمل التعليمة التوضيحية على كل من الفئات والدوال.

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class Audited

@Audited
class Account {
    @Audited
    fun withdraw() = "ok"
}

fun main() {
    println(Account().withdraw())
}

قيم المعاملات الافتراضية

يمكن أن تكون لمعاملات التعليقات التوضيحية قيم افتراضية، مما يتيح للمستدعين حذفها. وهذا يحافظ على إيجاز الحالات الشائعة.

annotation class Cache(val seconds: Int = 60)

@Cache
fun cheap() = 1

@Cache(seconds = 300)
fun expensive() = 2

fun main() {
    println("" + cheap() + " " + expensive())
}

معاملات المصفوفات

يمكنك استخدام أنواع المصفوفات. مرر القيم باستخدام بنية القيمة الحرفية للمصفوفة [ ... ] عند استخدام التعليمة التوضيحية.

annotation class Roles(val names: Array<String>)

@Roles(["admin", "editor"])
fun restricted() = "secret"

fun main() {
    println(restricted())
}

@Repeatable

لا يمكن أن تظهر التعليمة التوضيحية افتراضيًا إلا مرة واحدة لكل عنصر. أضف إليها @Repeatable لتطبيقها عدة مرات.

@Repeatable
annotation class Tag(val value: String)

@Tag("db")
@Tag("cache")
fun layered() = "ok"

fun main() {
    println(layered())
}

معاملات التعليقات التوضيحية المتداخلة

يمكن أن يكون معامل التعليمة التوضيحية نفسه تعليمة توضيحية أخرى، مما يتيح لك إنشاء بيانات وصفية منظمة.

annotation class Author(val name: String)
annotation class Module(val owner: Author)

@Module(Author("Grace"))
class Payments

fun main() {
    println("Nested annotation metadata defined")
}

تصميم تعليقات توضيحية جيدة

تتصف التعليمة التوضيحية المصممة جيدًا بما يلي:

لها غرض واضح ومحدد
تحدد @Target بحيث يصبح سوء استخدامها خطأً في وقت الترجمة
تستخدم الاحتفاظ من النوع RUNTIME فقط عندما يحتاج الانعكاس إليه
توفر قيمًا افتراضية منطقية

من التعريف إلى الاستخدام

لا يمثل تعريف التعليمة التوضيحية سوى نصف القصة. فهي بمفردها بيانات وصفية خاملة. ولا بد من وجود شيء يقرأها — وعادةً ما يكون ذلك الانعكاس في وقت التشغيل أو معالج التعليقات التوضيحية في وقت الترجمة. ستستخدم الانعكاس قريبًا.

تحقق سريع

اختبر مدى فهمك لتعريف التعليقات التوضيحية.

مراجعة

تعلمت كيفية تعريف التعليقات التوضيحية:

annotation class مع المعاملات
@Target لتقييد موضع الاستخدام
@Retention للتحكم في مدة البقاء
@Repeatable والقيم الافتراضية

التالي: فحص الأنواع باستخدام الانعكاس.

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

هل درس «تعريف Annotations» مجاني؟

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

ماذا ستتعلم في «تعريف Annotations»؟

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

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

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

كم من الوقت يستغرق درس «تعريف Annotations»؟

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

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

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

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

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