تطوير Android / الأساسي: أسس Android وCompose / الدرس 1
مشروعات Android وبيئة Studio وأدوات البناء
تتبّع تطبيق صغير لقائمة قراءة من الملفات المصدرية إلى الحزمة المثبتة، وافهم الإعدادات التي تتحكم بالتوافق.
في هذه الصفحة
أهداف الدرس
- ميّز بين بيئة التطوير وSDK وغلاف Gradle وإضافة Android إلى Gradle.
- اشرح إعدادات SDK دون الخلط بين الترجمة والدعم أثناء التشغيل.
تتبّع مسار البناء
تتيح Android Studio تحرير المشروع وفهرسته ومعاينته وتنقيحه، بينما ينفذ Gradle عملية البناء القابلة للتكرار. تضيف إضافة Android مهام البناء الخاصة بالنظام، ويوفر SDK واجهات المنصة وأدوات التغليف. تتحول شيفرة Kotlin إلى تعليمات قابلة للتنفيذ، وتحصل الموارد على معرّفات، ويصف ملف manifest نقاط الدخول. ملف APK حزمة قابلة للتثبيت، أما Android App Bundle فصيغة نشر تستطيع خدمة التوزيع إنتاج حزم APK ملائمة للأجهزة انطلاقاً منها. تساعد هذه الحدود على تمييز تحذير المحرر من فشل الترجمة أو التثبيت.
اقرأ بنية المشروع قبل تعديله
ابدأ بمشروع Compose مولّد من Studio بإصدارات القالب المتوافقة. يحدد settings.gradle.kts الوحدات المضمّنة وسياسة المستودعات، ويضبط ملف البناء الجذري الإضافات المشتركة، ويضبط app/build.gradle.kts وحدة التطبيق. توجد ملفات Kotlin في مجلدات المصدر والموارد في res. قد يوفر كتالوج الإصدارات أسماء مختصرة للإضافات والاعتماديات. احفظ غلاف Gradle وإعداداته في نظام التحكم بالإصدارات ليستخدم مطور آخر التوزيعة نفسها. لا تنسخ ملف بناء كاملاً من درس غير مرتبط إلى مشروع قائم.
android {
namespace = "com.example.reading"
defaultConfig {
applicationId = "com.example.reading"
versionCode = 1
versionName = "1.0"
}
}توضع هذه الكتلة في app/build.gradle.kts مع الاحتفاظ بإضافات القالب وإعدادات SDK. يحدد namespace نطاق الأصناف المولّدة، ويحدد applicationId التطبيق المثبت. تغيير أحدهما لا ينقل بيانات المستخدم المخزنة تلقائياً.
افصل قرارات SDK الثلاثة
يحدد compileSdk رموز المنصة التي تراها أداة الترجمة. يعلن minSdk أقدم مستوى API تدعمه الأجهزة، مع مراعاة متطلبات المكتبات أيضاً. يختار targetSdk سلوك التوافق ويشير إلى تغييرات المنصة التي عالجها التطبيق، ولا يمنع التثبيت على Android أحدث. اختر القيم الفعلية وفق متطلبات المشروع والأدوات المتوافقة المثبتة، ثم راجع قواعد التوزيع الحالية قبل الإصدار. نجاح الترجمة لا يثبت وجود واجهة حديثة على جميع الأجهزة المدعومة؛ احمِ استدعاءها بشرط أو استخدم تجريداً مناسباً من AndroidX.
اربط الموارد بنقطة الدخول
نشاط التشغيل المولّد مكوّن Android وليس دالة main عادية. تربط الدالة onCreate واجهة Compose عبر setContent. تتيح مراجع الموارد للنظام اختيار النص المترجم والأصول البديلة دون شروط متناثرة. احتفظ بقالب السمة وإدخال manifest أثناء التعلم. تعرض المعاينة دالة تركيبية داخل بيئة المحرر، فتفيد في فحص التخطيط لكنها لا تختبر التثبيت أو الأذونات أو إعادة إنشاء العملية أو الشبكة الحقيقية. تحتاج هذه السلوكيات لاحقاً إلى بيئة اختبار مناسبة.
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent { MaterialTheme { Text("Reading list") } }
}
}استخدم حزمة القالب واستيراداته الخاصة بـ Bundle وComponentActivity وsetContent وMaterialTheme وText. يوفر القالب اعتماديات AndroidX وCompose. هذا مقتطف تعليمي يحذف بقية المشروع ولا يعمل منفرداً.
شخّص الفشل حسب ترتيب الاعتماد
حدّد أولاً هل وقع الفشل أثناء المزامنة أم الترجمة أم التغليف أم التثبيت أم التشغيل. اقرأ أول خطأ ذي صلة وموقع ملفه بدلاً من اعتبار رسالة فشل المهمة الأخيرة سبباً. افحص توافق الغلاف والإضافة وKotlin وJDK ومترجم Compose معاً قبل ترقية جزء واحد. افصل إعدادات التنقيح عن توقيع الإصدار ولا تحفظ أسرار التوقيع في المستودع. دوّن الأدوات التي اختُبرت في وثائق المشروع ليملك التحديث القادم نقطة بداية معروفة ويُراجع كتغيير مقصود.
الأخطاء الشائعة وإصلاحها
تعجز مزامنة Gradle عن إيجاد إضافة
- لماذا يحدث؟
- يختلف الاسم المختصر أو المستودع عن إعداد المشروع المولّد.
- كيف تصلحه؟
- قارن الإعدادات وكتالوج الإصدارات بالقالب ثم صحّح إحداثيات الاعتماد المحددة.
- كيف تتجنب تكراره؟
- راجع تغييرات الاعتماديات معاً واحتفظ بإصدارات قابلة لإعادة البناء.
تُترجم ميزة لكنها تتعطل على جهاز أقدم
- لماذا يحدث؟
- اعتُبر compileSdk ضماناً للتوفر أثناء التشغيل.
- كيف تصلحه؟
- احمِ الواجهة بشرط مستوى الجهاز أو استخدم تنفيذاً متوافقاً من AndroidX.
- كيف تتجنب تكراره؟
- اختبر أدنى API مدعوم إلى جانب بيئة تستهدف السلوك الحالي.
يُثبت التحديث كتطبيق منفصل
- لماذا يحدث؟
- تغير applicationId بين عمليتي البناء.
- كيف تصلحه؟
- أعد هوية التطبيق المقصودة وتحقق من لاحقة متغير البناء.
- كيف تتجنب تكراره؟
- عامل هوية التطبيق وهوية التوقيع كمتطلبات إصدار.
اختبر فهمك
1. يترجم مشروع باستخدام SDK أحدث لكنه يدعم هواتف أقدم. هل يجعل targetSdk وحده استدعاء واجهة حديثة دون شرط آمناً؟
اعرض الحل المشروح
لا. تعرف أداة الترجمة الرمز عبر compileSdk، لكن الجهاز ينفذ مستوى API الخاص به. افحص التوفر أثناء التشغيل أو استخدم تجريداً مدعوماً، واختبر ذلك المسار على أقدم إعداد مدعوم. يتطلب رفع targetSdk أيضاً مراجعة تغييرات السلوك بصورة مستقلة.
2. تعمل معاينة Compose لدى زميل لكن التطبيق لا يبدأ. ضع تسلسلاً مركزاً للتحقيق.
اعرض الحل المشروح
ابنِ المتغير المقصود وافحص أخطاء التغليف والتثبيت، ثم افحص تعطل التشغيل وإعلان النشاط في manifest. تأكد من استيفاء الجهاز لـ minSdk. نجاح المعاينة يثبت فقط قدرة الأدوات على عرض جزء من الواجهة، ولا يثبت صحة التطبيق المغلف أو إعداد الجهاز.
أهم ما تعلمته
- البناء مسار ذو مراحل فشل متميزة.
- تصف إعدادات SDK عقود توافق مختلفة.
- احفظ مجموعة أدوات متوافقة ومعروفة قبل التجريب.