يمكن أن يساعدك استخدام أدوات فحص الرموز، مثل lint، في العثور على
المشاكل وتحسين الرمز، ولكن لا يمكن لأدوات الفحص استنتاج الكثير من المعلومات. على سبيل المثال، تستخدم أرقام تعريف موارد Androidint
لتحديد السلاسل والرسومات والألوان وأنواع الموارد الأخرى،
لذلك لا يمكن لأدوات الفحص معرفة ما إذا كنت قد حدّدت مورد سلسلة في المكان الذي كان يجب فيه تحديد لون. يعني هذا الموقف أنّه قد يتم عرض تطبيقك بشكل غير صحيح أو قد يتعذّر تشغيله على الإطلاق،
حتى إذا كنت تستخدم ميزة فحص الرموز البرمجية.
تتيح لك التعليقات التوضيحية تقديم تلميحات لأدوات فحص التعليمات البرمجية، مثل أداة Lint، للمساعدة في اكتشاف مشكلات التعليمات البرمجية الأكثر دقة. تتم إضافة التعليقات التوضيحية كعلامات بيانات وصفية تعلقها بالمتغيّرات والاقتباسات والقيم المعروضة لفحص القيم المعروضة للطريقة والمَعلمات التي تم تمريرها والمتغيّرات المحلية والاقتباسات والحقول. عند استخدام التعليقات التوضيحية مع أدوات فحص الرموز البرمجية، يمكن أن تساعدك في رصد مشاكل مثل استثناءات مؤشر الفراغ وحالات تعارض نوع المورد.
يتيح Android مجموعة متنوعة من التعليقات التوضيحية من خلال
مكتبة التعليقات التوضيحية في Jetpack.
يمكنك الوصول إلى المكتبة من خلال حزمة androidx.annotation
.
ملاحظة: إذا كانت الوحدة تعتمد على معالج التعليقات التوضيحية،
عليك استخدام إعدادات الاعتماد kapt
أو ksp
لـ Kotlin
أو إعدادات الاعتماد annotationProcessor
لـ Java لإضافة
هذا الاعتماد.
إضافة تعليقات توضيحية إلى مشروعك
لتفعيل التعليقات التوضيحية في مشروعك، أضِف التبعية androidx.annotation:annotation
إلى مكتبتك أو تطبيقك. ويتم التحقّق من أي تعليقات توضيحية تضيفها عند تنفيذ فحص код
أو مهمة lint
.
إضافة التبعية لـ Jetpack Annotations library
يتم نشر مكتبة Jetpack Annotations على
مستودع Maven من Google.
لإضافة مكتبة Jetpack Anotations إلى مشروعك، أدرِج السطر التالي
في كتلة dependencies
من ملف build.gradle
أوملف
build.gradle.kts
:
dependencies { implementation("androidx.annotation:annotation:1.9.1") }
dependencies { implementation 'androidx.annotation:annotation:1.9.1' }
إذا كنت تستخدم تعليقات توضيحية في وحدة مكتبتك، يتم تضمين التعليقات التوضيحية كجزء من ملف annotations.zip
بتنسيق XML ضمن ملف ملف أرشيف Android (AAR). لا تؤدي إضافة تبعية androidx.annotation
إلى تقديم اعتمادية لأي مستخدمين في مرحلة ما بعد الإنتاج في مكتبتك.
ملاحظة: إذا كنت تستخدم مكتبات Jetpack الأخرى،
قد لا تحتاج إلى إضافة الاعتمادية androidx.annotation
. بما أنّ العديد من مكتبات
Jetpack الأخرى تعتمد على مكتبة التعليقات التوضيحية، قد يكون بإمكانك الوصول إلى التعليقات
التوضيحية.
للحصول على قائمة كاملة بالتعليقات التوضيحية المضمّنة في مستودع Jetpack، يمكنك الاطّلاع على
مرجع مكتبة التعليقات التوضيحية في Jetpack أو استخدام ميزة الإكمال التلقائي لعرض الخيارات المتاحة لعبارة
import androidx.annotation.
.
إجراء عمليات فحص للرموز البرمجية
لبدء فحص الرمز من Android Studio، والذي يتضمّن التحقّق من التعليقات التوضيحية وفحص lint التلقائي، اختَر تحليل > فحص الرمز من الجدول. يعرض Android Studio رسائل تعارض لرصد المشاكل المحتمَلة التي يتعارض فيها الرمز البرمجي مع التعليقات التوضيحية واقتراح حلول محتملة.
يمكنك أيضًا فرض التعليقات التوضيحية من خلال تشغيل المهمة lint
باستخدام سطر الأوامر. على الرغم من أنّ هذا قد يكون مفيدًا للإبلاغ عن المشاكل
باستخدام خادم دمج مستمر، لا تفرض مهمة lint
استخدام التعليقات التوضيحية
للقيمة الخالية (الموضَّحة في القسم التالي)، بل ينفّذ Android Studio ذلك فقط. لمزيد من
المعلومات عن تفعيل عمليات فحص lint
وتنفيذها، اطّلِع على مقالة تحسين الرمز البرمجي باستخدام عمليات فحص lint.
على الرغم من أنّ تعارضات التعليقات التوضيحية تؤدي إلى ظهور تحذيرات، لا تمنع هذه التحذيرات compilingتطبيقك.
التعليقات التوضيحية للقيمة الخالية
يمكن أن تكون التعليقات التوضيحية حول القيمة الخالية مفيدة في رمز Java لفرض ما إذا كان يمكن أن تكون القيم خالية. وهي أقل فائدة في رمز Kotlin، لأنّ Kotlin تتضمّن قواعد إمكانية قبول القيم الفارغة التي يتم فرضها في وقت الترجمة.أضِف التعليقَين التوضيحيَين @Nullable
و
@NonNull
للتحقّق من قيمة فارغة لمتغيّر أو مَعلمة أو قيمة معروضة. تشير التعليق التوضيحي @Nullable
إلى متغير أو معلَمة أو قيمة معروضة يمكن أن تكون فارغة.
يشير الرمز @NonNull
إلى متغيّر أو مَعلمة أو قيمة معروضة لا يمكن أن تكون فارغة.
على سبيل المثال، إذا تم تمرير متغيّر محلي يحتوي على قيمة فارغة كمَعلمة إلى طريقة
مع إرفاق التعليق التوضيحي @NonNull
بهذه المَعلمة، يؤدي إنشاء الرمز إلى توليد
تحذير يشير إلى تعارض غير فارغ. بالإضافة إلى ذلك، يؤدي محاولة الإشارة إلى نتيجة
طريقة تم وضع علامة @Nullable
عليها بدون التحقّق أولاً مما إذا كانت النتيجة فارغة إلى توليد
تحذير فارغ. لا تستخدم @Nullable
إلا مع القيمة المعروضة لطريقة ما
إذا كان يجب تحديد قيمة فارغة في كل استخدام لهذه الطريقة بشكل صريح.
يوضّح المثال التالي حالة عدم السماح بالقيمة الخالية. لا يستفيد نموذج رمز Kotlin من
التعليق التوضيحي @NonNull
لأنّه تتم إضافته تلقائيًا إلى الرمز الثنائي الذي تم إنشاؤه
عند تحديد نوع غير قابل للقيمة الخالية. يستفيد مثال Java من التعليق التوضيحي @NonNull
على المَعلمتَين context
وattrs
للتحقّق من أنّ قيم المَعلمات المُرسَلة
ليست فارغة. وتتحقّق أيضًا من أنّ الطريقة onCreateView()
نفسها لا تعرض قيمة فارغة:
... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String?, context: Context, attrs: AttributeSet ): View? { ... } ...
import androidx.annotation.NonNull; ... /** Add support for inflating the <fragment> tag. **/ @NonNull @Override public View onCreateView(String name, @NonNull Context context, @NonNull AttributeSet attrs) { ... } ...
تحليل قابلية العدم
يتيح "استوديو Android" إجراء تحليل للقيم الفارغة لاستنتاج تعليقات توضيحية للقيم الفارغة وإدراجها في الرمز البرمجي تلقائيًا. يفحص تحليل قابلية العدم العقود في جميع التسلسلات الهرمية للطرق في الرمز البرمجي لرصد ما يلي:
- استدعاء طرق يمكنها عرض قيمة فارغة
- الطرق التي يجب ألا تُعرِض قيمة فارغة
- المتغيّرات، مثل الحقول والمتغيّرات المحلية والمعلَمات التي يمكن أن تكون فارغة.
- المتغيّرات، مثل الحقول والمتغيّرات المحلية والمَعلمات، التي لا يمكنها احتواء قيمة فارغة
بعد ذلك، يُدرج التحليل تلقائيًا التعليقات التوضيحية المناسبة للقيم الخالية في المواقع الجغرافية التي تم رصدها.
لإجراء تحليل القيم الفارغة في "استوديو Android"، انقر على تحليل >
استنتاج القيم الفارغة. يُدرج Android Studio التعليقَين التوضيحيَين @Nullable
و@NonNull
في Android في
المواقع التي تم رصدها في الرمز البرمجي. بعد إجراء تحليل فارغ، من المستحسن التحقق من التعليقات التوضيحية التي تم إدخالها.
ملاحظة: عند إضافة تعليقات توضيحية عن القيم الخالية، قد يقترح خيار الإكمال التلقائي
تعليقات توضيحية IntelliJ
@Nullable
و
@NotNull
بدلاً من تعليقات توضيحية Android عن القيم الخالية
وقد يستورد تلقائيًا المكتبة المقابلة. ومع ذلك، لا يبحث مدقّق الأخطاء lint في "استوديو Android" سوى عن التعليقات التوضيحية للقيم الخالية في Android. عند التحقّق من التعليقات التوضيحية
، تأكَّد من أنّ مشروعك يستخدم التعليقات التوضيحية للقيم الخالية في Android حتى يتمكّن فحص lint من إعلامك بشكل صحيح أثناء فحص الرمز.
التعليقات التوضيحية للمراجع
يمكن أن يكون التحقّق من أنواع الموارد مفيدًا لأنّ نظام التشغيل Android يُحيل إلى الموارد، مثل موارد drawable وstring، ويتم تمريرها كأرقام صحيحة.
يمكن تمرير الرمز الذي يتوقّع أن تشير المَعلمة إلى نوع معيّن من الموارد، مثل String
،
إلى نوع المرجع المتوقّع int
، ولكنّه يشير في الواقع إلى نوع مختلف
من الموارد، مثل مورد R.string
.
على سبيل المثال، أضِف تعليقات توضيحية @StringRes
لمحاولة معرفة ما إذا كانت مَعلمة المورد تحتوي على مرجع R.string
، كما هو موضّح هنا:
abstract fun setTitle(@StringRes resId: Int)
public abstract void setTitle(@StringRes int resId)
أثناء فحص الرمز، يُنشئ التعليق التوضيحي تحذيرًا إذا لم يتم تمرير مرجع R.string
في المَعلمة.
يمكن
إضافة تعليقات توضيحية لأنواع الموارد الأخرى، مثل @DrawableRes
و@DimenRes
و@ColorRes
و@InterpolatorRes
، باستخدام تنسيق التعليق التوضيحي نفسه وتشغيلها أثناء فحص الرمز.
إذا كانت المَعلمة
تتوافق مع أنواع موارد متعدّدة، يمكنك وضع أكثر من تعليق توضيحي لنوع واحد من الموارد على مَعلمة معيّنة. استخدِم @AnyRes
للإشارة إلى أنّ المَعلمة المُشارَك فيها تعليقات توضيحية يمكن أن تكون أيّ نوع من موارد R
.
على الرغم من أنّه يمكنك استخدام @ColorRes
لتحديد أنّ المَعلمة повинна تكون موردًا للألوان، لا يتم التعرّف على عدد صحيح للألوان (بتنسيق RRGGBB
أو
AARRGGBB
) كمورد ألوان. بدلاً من ذلك، استخدِم التعليق التوضيحي @ColorInt
لتحديد أنّ المَعلمة يجب أن تكون عددًا صحيحًا للون. ستُبلغ أدوات الإنشاء عن الرمز غير الصحيح الذي
يُمرِّر معرّف مورد لون مثل android.R.color.black
بدلاً من عدد صحيح للّون
إلى الطرق المُشارَك فيها تعليقات توضيحية.
التعليقات التوضيحية لسلسلة المحادثات
تتحقّق التعليقات التوضيحية لسلسلة المحادثات ممّا إذا تم استدعاء طريقة من نوع معيّن من سلسلة محادثات. يمكن استخدام التعليقات التوضيحية التالية في السلسلة:
تتعامل أدوات الإنشاء مع التعليقات التوضيحية @MainThread
و
@UiThread
على أنّها قابلة للتبديل، لذا يمكنك استدعاء طرق @UiThread
من طرق @MainThread
والعكس صحيح. ومع ذلك، من الممكن أن يختلف مؤشر تسلسل واجهة المستخدم عن مؤشر التسلسل الرئيسي، في حال تطبيقات النظام التي تتضمّن طرق عرض متعددة
على مؤشرات تسلسل مختلفة. وبالتالي، يجب إضافة تعليقات توضيحية إلى الطرق المرتبطة بالعرض الهرمي للتطبيق من خلال
@UiThread
وإضافة تعليقات توضيحية إلى الطرق المرتبطة بدورة حياة التطبيق فقط من خلال
@MainThread
.
إذا كانت جميع الطرق في فئة تتشارك متطلبات المعالجة المتعدّدة ال threads نفسها، يمكنك إضافة تعليق توضيحي واحد لسلسلة رسائل إلى الفئة للتحقّق من أنّه يتم استدعاء جميع الطرق في الفئة من النوع نفسه من سلسلة الرسائل.
من الاستخدامات الشائعة للتعليقات التوضيحية للخيوط هي التحقّق من أنّ الطرق أو الفئات التي تمّت إضافة تعليق توضيحي إليها باستخدام @WorkerThread
يتمّ استدعاؤها فقط من سلسلة مهام خلفية مناسبة.
التعليقات التوضيحية لقيود القيمة
استخدِم التعليقات التوضيحية @IntRange
و
@FloatRange
و
@Size
لمحاولة التحقّق من صحة قيم المَعلمات التي تم تمريرها. يكون كلّ من @IntRange
و@FloatRange
مفيدًا للغاية عند تطبيقهما على المَعلمات التي يُرجّح أن يخطئ فيها المستخدِمون في النطاق.
يتحقق التعليق التوضيحي @IntRange
من أنّ قيمة المَعلمة الكاملة أو الطويلة ضمن نطاق محدّد. يشير المثال التالي إلى أنّه يجب أن تحتوي المَعلمة alpha
على قيمة عددية من 0 إلى 255:
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }
public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }
يتحقّق التعليق التوضيحي @FloatRange
مما إذا كانت قيمة المَعلمة المتغيرة أو المَعلمة المتغيرة المزدوجة
ضمن نطاق محدّد من قيم النقطة العائمة. يشير المثال التالي إلى أنّ مَعلمة alpha
يجب أن تحتوي على قيمة عائمة تتراوح بين 0.0 و1.0:
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
يتحقّق التعليق التوضيحي @Size
من حجم مجموعة أو مصفوفة أو طول سلسلة. يمكن استخدام التعليق التوضيحي @Size
للتأكّد من السمات التالية:
- الحد الأدنى للحجم، مثل
@Size(min=2)
- الحد الأقصى للحجم، مثل
@Size(max=2)
- الحجم الدقيق، مثل
@Size(2)
- رقم يجب أن يكون حجم الصورة مضاعِفًا له، مثل
@Size(multiple=2)
على سبيل المثال، يتحقّق @Size(min=1)
من أنّ المجموعة ليست فارغة، ويتحقّق @Size(3)
من أنّ الصفيف يحتوي على ثلاث قيم بالضبط.
يشير المثال التالي إلى أنّ مصفوفة location
يجب أن تحتوي على عنصر واحد على الأقل:
fun getLocation(button: View, @Size(min=1) location: IntArray) { button.getLocationOnScreen(location) }
void getLocation(View button, @Size(min=1) int[] location) { button.getLocationOnScreen(location); }
التعليقات التوضيحية للأذونات
يمكنك استخدام التعليق التوضيحي @RequiresPermission
للتحقق من أذونات المتصل بطريقة ما. للتحقّق من الحصول على إذن واحد من قائمة الأذونات الصالحة، استخدِم السمة anyOf
. للتحقّق من توفّر مجموعة من
الأذونات، استخدِم السمة allOf
. يوضّح المثال التالي تعليقًا توضيحيًا على الإجراء
setWallpaper()
للإشارة إلى أنّه يجب أن يكون لدى المُرسِل للإجراء إذن
permission.SET_WALLPAPERS
:
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
@RequiresPermission(Manifest.permission.SET_WALLPAPER) public abstract void setWallpaper(Bitmap bitmap) throws IOException;
يتطلّب المثال التالي أن يكون لدى المُرسِل لطريقة copyImageFile()
إذن بالقراءة في وحدة التخزين الخارجية وإذن بالقراءة في البيانات الوصفية لمكان
الصورة المنسوخة:
@RequiresPermission(allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ]) fun copyImageFile(dest: String, source: String) { ... }
@RequiresPermission(allOf = { Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION}) public static final void copyImageFile(String dest, String source) { //... }
بالنسبة إلى الأذونات في النوايا، ضَع شرط الإذن في حقل السلسلة الذي يحدِّد اسم إجراء النية:
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
@RequiresPermission(android.Manifest.permission.BLUETOOTH) public static final String ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";
بالنسبة إلى أذونات مقدّمي المحتوى الذين يحتاجون إلى أذونات منفصلة للوصول إلى القراءة والكتابة، يجب تضمين كلّ شرط من شروط الأذونات في تعليق توضيحي @RequiresPermission.Read
أو @RequiresPermission.Write
:
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS)) val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
الأذونات غير المباشرة
عندما يعتمد أحد الأذونات على القيمة المحدّدة التي يتم تقديمها إلى مَعلمة إحدى الطرق، استخدِم
@RequiresPermission
على المَعلمة نفسها بدون إدراج الأذونات المحدّدة.
على سبيل المثال، تستخدم الطريقة startActivity(Intent)
إذنًا غير مباشر على النية التي تم تمريرها إلى الطريقة:
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)
عند استخدام الأذونات غير المباشرة، تُجري أدوات الإنشاء تحليلًا لتدفّق البيانات للتحقّق مما إذا كانت العبارة
التي تم تمريرها إلى الطريقة تحتوي على أي تعليقات توضيحية @RequiresPermission
. وبعد ذلك،
تفرض أي تعليقات توضيحية حالية من المَعلمة على الطريقة نفسها. في مثال startActivity(Intent)
، تتسبب التعليقات التوضيحية في الفئة Intent
في ظهور التحذيرات الناتجة عن الاستخدامات غير الصالحة لـ startActivity(Intent)
عند تمرير إجراء إلى الطريقة بدون الحصول على الأذونات المناسبة كما هو موضّح في الشكل 1.

الشكل 1. التحذير الذي تم إنشاؤه من تعليق توضيحي غير مباشر
للأذونات في طريقة startActivity(Intent)
تنشئ أدوات الإنشاء التحذير بشأن startActivity(Intent)
من التعليق التوضيحي
على اسم إجراء الهدف المقابل في فئة Intent
:
@RequiresPermission(Manifest.permission.CALL_PHONE) const val ACTION_CALL = "android.intent.action.CALL"
@RequiresPermission(Manifest.permission.CALL_PHONE) public static final String ACTION_CALL = "android.intent.action.CALL";
إذا لزم الأمر، يمكنك استبدال @RequiresPermission
بـ @RequiresPermission.Read
أو @RequiresPermission.Write
عند إضافة تعليقات توضيحية إلى معلَمة طريقة ما. ومع ذلك، بالنسبة إلى الأذونات غير المباشرة، يجب عدم استخدام @RequiresPermission
مع التعليقات التوضيحية لأذونات القراءة أو الكتابة.
التعليقات التوضيحية للقيمة المعروضة
استخدِم التعليق التوضيحي @CheckResult
لتأكيد استخدام نتيجة الطريقة أو القيمة المعروضة. بدلاً من إضافة التعليق التوضيحي @CheckResult
إلى كل @CheckResult
طريقة غير فارغة، أضِف التعليق التوضيحي لتوضيح نتائج @CheckResult
الطرق التي قد تكون مربكة.
على سبيل المثال، غالبًا ما يظن مطوّرو Java الجدد عن طريق الخطأ أنّ <String>.trim()
يزيل المسافات البيضاء من السلسلة الأصلية. إن التعليق التوضيحي على الطريقة باستخدام علامات @CheckResult
يستخدم <String>.trim()
حيث لا يفعل المتصل أي شيء بالقيمة التي تعرضها الطريقة.
يضيف المثال التالي تعليقات توضيحية إلى الطريقة checkPermissions()
للتحقّق مما إذا كانت القيمة المعروضة
للطريقة مُشار إليها فعليًا. ويُشير أيضًا إلى enforcePermission()
method كطريقة يمكن أن نقترحها على المطوّر كبديل:
@CheckResult(suggest = "#enforcePermission(String,int,int,String)") abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int
@CheckResult(suggest="#enforcePermission(String,int,int,String)") public abstract int checkPermission(@NonNull String permission, int pid, int uid);
التعليقات التوضيحية في CallSuper
استخدِم التعليق التوضيحي @CallSuper
لتأكيد أنّ الطريقة التي تلغي طريقة أخرى تستدعي تنفيذ الطريقة الأصلية.
يُعلِق المثال التالي onCreate()
تعليقًا توضيحيًا لضمان أنّ أي تنفيذات لطريقة super.onCreate()
تُطلِق super.onCreate()
:
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
@CallSuper protected void onCreate(Bundle savedInstanceState) { }
التعليقات التوضيحية لأنواع البيانات
تتحقّق التعليقات التوضيحية لنوع البيانات من ما إذا كانت مَعلمة معيّنة أو قيمة معروضة أو حقل معيّن يشير إلى مجموعة معيّنة من الثوابت. وتتيح أيضًا إكمال الرموز البرمجية من أجل تقديم الثوابت المسموح بها تلقائيًا.
استخدِم التعليقات التوضيحية @IntDef
و
@StringDef
لإنشاء تعليقات توضيحية مُدرَجة لمجموعات الأعداد الصحيحة والسلاسل من أجل التحقّق من صحة
أنواع أخرى من مراجع الرموز البرمجية.
تستخدِم التعليقات التوضيحية لأنواع البيانات @interface
للإعلان عن نوع التعليق التوضيحي الجديد المُدرَج.
يضيف كلّ من @IntDef
و@StringDef
التوضيحية، بالإضافة إلى
@Retention
، تعليقات توضيحية إلى التعليق التوضيحي الجديد، وهما ضروريان لتحديد النوع العددي. يطلب التعليق التوضيحي @Retention(RetentionPolicy.SOURCE)
من المحول البرمجي
عدم تخزين بيانات التعليقات التوضيحية العددية في ملف .class
.
يوضّح المثال التالي خطوات إنشاء تعليق توضيحي يتحقّق مما إذا كانت القيمة التي تم تمريرها كمَعلمة طريقة تشير إلى إحدى الثوابت المحدّدة:
import androidx.annotation.IntDef //... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(AnnotationRetention.SOURCE) @IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS) annotation class NavigationMode // Declare the constants. const val NAVIGATION_MODE_STANDARD = 0 const val NAVIGATION_MODE_LIST = 1 const val NAVIGATION_MODE_TABS = 2 abstract class ActionBar { // Decorate the target methods with the annotation. // Attach the annotation. @get:NavigationMode @setparam:NavigationMode abstract var navigationMode: Int }
import androidx.annotation.IntDef; //... public abstract class ActionBar { //... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(RetentionPolicy.SOURCE) @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS}) public @interface NavigationMode {} // Declare the constants. public static final int NAVIGATION_MODE_STANDARD = 0; public static final int NAVIGATION_MODE_LIST = 1; public static final int NAVIGATION_MODE_TABS = 2; // Decorate the target methods with the annotation. @NavigationMode public abstract int getNavigationMode(); // Attach the annotation. public abstract void setNavigationMode(@NavigationMode int mode); }
عند إنشاء هذا الرمز، يتم إنشاء تحذير إذا لم تشير المعلَمة mode
إلى أحد الثوابت المحددة (NAVIGATION_MODE_STANDARD
أو NAVIGATION_MODE_LIST
أو NAVIGATION_MODE_TABS
).
يمكنك دمج @IntDef
و@IntRange
للإشارة إلى أن العدد الصحيح يمكن أن يكون إما مجموعة معيّنة من الثوابت أو قيمة ضمن نطاق.
تفعيل دمج الثوابت مع العلامات
إذا كان بإمكان المستخدمين دمج الثوابت المسموح بها مع علامة (مثل |
&
و^
وما إلى ذلك)، يمكنك تحديد تعليق توضيحي باستخدام سمة
flag
للتحقّق مما إذا كانت المَعلمة أو القيمة المعروضة تشير إلى نمط صالح.
ينشئ المثال التالي التعليق التوضيحي DisplayOptions
مع قائمة بثوابت
DISPLAY_
الصالحة:
import androidx.annotation.IntDef ... @IntDef(flag = true, value = [ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM ]) @Retention(AnnotationRetention.SOURCE) annotation class DisplayOptions ...
import androidx.annotation.IntDef; ... @IntDef(flag=true, value={ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM }) @Retention(RetentionPolicy.SOURCE) public @interface DisplayOptions {} ...
عند إنشاء رمز باستخدام علامة تعليق توضيحي، يتم إنشاء تحذير إذا كانت المَعلمة المزيّنة أو القيمة المعروضة لا تشير إلى نمط صالح.
إبقاء التعليق التوضيحي
يضمن التعليق التوضيحي @Keep
عدم إزالة فئة أو طريقة تمّت إضافة تعليق توضيحي إليها عند تصغير الرمز المبرمَج
في وقت الإنشاء. تتم عادةً
إضافة هذا التعليق التوضيحي إلى الطرق والفئات التي يتم الوصول إليها من خلال ميزة "الاستكشاف" لمنع المُجمِّع من
التعامل مع الرمز البرمجي على أنّه غير مستخدَم.
تنبيه: إنّ الفئات والطرق التي تضيف إليها تعليقات توضيحية باستخدام @Keep
تظهر دائمًا في حزمة APK الخاصة بتطبيقك، حتى إذا لم تُشِر أبدًا إلى هذه الفئات والطرق ضمن منطق تطبيقك.
للحفاظ على حجم تطبيقك صغيرًا، ننصحك بالتفكير في ما إذا كان من الضروري الاحتفاظ
بكل تعليق توضيحي @Keep
في تطبيقك. إذا كنت تستخدِم ميزة "الاستدلال" لمحاولة
الوصول إلى فئة أو طريقة مُشارَك فيها تعليق توضيحي، استخدِم شرطًا من نوع
-if
في قواعد ProGuard، مع تحديد الفئة
التي تُجري طلبات الاستدلال.
لمزيد من المعلومات حول كيفية تصغير الرمز البرمجي وتحديد الرمز الذي لا تتم إزالته، اطّلِع على مقالة تصغير حجم تطبيقك وإخفاء مفاتيح فك التشفير وتحسينه.
التعليقات التوضيحية لمستوى عرض الرمز
استخدِم التعليقات التوضيحية التالية للإشارة إلى مستوى ظهور أجزاء معيّنة من الرمز البرمجي، مثل methods أو classes أو fields أو packages.
إظهار الرمز البرمجي للاختبار
تشير
@VisibleForTesting
أنّ الطريقة التي تتضمّن تعليقات توضيحية تكون مرئية أكثر من اللازم عادةً لجعل
الطريقة قابلة للاختبار. يحتوي هذا التعليق التوضيحي على وسيطة otherwise
اختيارية تتيح لك تحديد مستوى إذن الوصول إلى الطريقة في حال عدم الحاجة إلى جعله متاحًا
للاختبار. يستخدم Lint الوسيطة otherwise
لفرض مستوى العرض المقصود.
في المثال التالي، تكون قيمة myMethod()
عادةً private
، ولكنّها
package-private
للاختبارات. باستخدام التصنيف VisibleForTesting.PRIVATE
، يعرض lint رسالة إذا تم استدعاء هذه الطريقة من خارج
سياق الوصول المسموح به من خلال private
، مثل وحدة تجميع مختلفة.
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { ... }
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) void myMethod() { ... }
يمكنك أيضًا تحديد @VisibleForTesting(otherwise = VisibleForTesting.NONE)
للإشارة إلى أنّ طريقة الاختبار تتوفّر فقط للاختبار. هذا النموذج هو نفسه المستخدَم في
@RestrictTo(TESTS)
. كلتاهما تُجريان فحص الوبر نفسه.
حظر واجهة برمجة تطبيقات
يشير التعليق التوضيحي @RestrictTo
إلى أنّ إمكانية الوصول إلى واجهة برمجة التطبيقات التي تتضمّن تعليقات توضيحية (الحزمة أو الفئة أو الطريقة) محدود،
على النحو التالي:
الفئات الفرعية
استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.SUBCLASSES)
لحصر الوصول إلى واجهة برمجة التطبيقات على الفئات الفرعية فقط.
لا يمكن الوصول إلى واجهة برمجة التطبيقات هذه إلا من خلال الصفوف التي تمديدها من الصف المُشارَك. لا يكون معدِّل Java
protected
تقييديًا بما يكفي، لأنّه يسمح بالوصول
من فئات غير ذات صلة ضمن الحزمة نفسها. هناك أيضًا حالات تريد فيها ترك public
public
لتوفير المرونة في المستقبل، لأنّه لا يمكنك أبدًا إنشاء public
protected
تم تجاوزه سابقًا، ولكنك تريد تقديم تلميح مفاده أنّ الفئة مخصّصة للاستخدامات داخل الفئة أو من الفئات الفرعية فقط.
المكتبات
استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
لمحاولة
حظر الوصول إلى واجهة برمجة التطبيقات على مكتباتك فقط.
ويمكن لرمز المكتبة فقط الوصول إلى واجهة برمجة التطبيقات التي تتضمّن تعليقات توضيحية. يتيح لك ذلك ليس فقط تنظيم رموذك
في أي تسلسل هرمي للحزمة تريده، بل يتيح لك أيضًا مشاركة
الرمز بين مجموعة من المكتبات ذات الصلة. يتوفّر هذا الخيار حاليًا لمكتبات
Jetpack التي تحتوي على الكثير من رموز التنفيذ غير المخصّصة للاستخدام الخارجي، ولكن يجب أن تكون
public
لمشاركتها في مكتبات Jetpack التكميلية المختلفة.
الاختبار
استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.TESTS)
لمنع المطوّرين الآخرين من الوصول إلى واجهات برمجة التطبيقات المخصّصة للاختبار.
لا يمكن سوى لرمز الاختبار الوصول إلى واجهة برمجة التطبيقات التي تمت عليها تعليقات توضيحية. يمنع ذلك المطوّرين الآخرين من استخدام واجهات برمجة التطبيقات المخصّصة لأغراض الاختبار فقط.