ضبط وحدة التطبيق

توضّح هذه الصفحة إعدادات التطبيق المفيدة في ملف build.gradle.kts على مستوى الوحدة. بالإضافة إلى تقديم نظرة عامة على السمات المهمة التي تم ضبطها في ملف build.gradle.kts، يمكنك التعرّف على كيفية:

  • تغيير رقم تعريف التطبيق لإعدادات التصميم المختلفة
  • يمكنك تعديل مساحة الاسم بأمان بشكل مستقل عن معرّف التطبيق.

ضبط معرّف التطبيق

يحتوي كل تطبيق Android على معرّف تطبيق فريد يشبه اسم حزمة Java أو Kotlin، مثل com.example.myapp. يحدِّد هذا المعرّف تطبيقك بشكلٍ فريد على الجهاز وفي "متجر Google Play".

يتم تحديد رقم تعريف تطبيقك من خلال السمة applicationId في ملف build.gradle.kts الخاص بالوحدة، كما هو موضّح هنا. عدِّل قيمة applicationId من خلال استبدال com.example.myapp بمعرّف تطبيقك:

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

أنيق

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

على الرغم من أنّ معرّف التطبيق يشبه اسم حزمة Kotlin أو Java التقليدي، إلا أنّ قواعد تسمية معرّف التطبيق أكثر تقييدًا:

  • يجب أن يتضمّن جزأين على الأقل (نقطة واحدة أو أكثر).
  • يجب أن يبدأ كل قسم بحرف.
  • يجب أن تكون جميع الأحرف أبجدية رقمية أو شرطة سفلية [a-zA-Z0-9_].

عند إنشاء مشروع جديد في "استوديو Android"، يتم تلقائيًا تعيين اسم الحزمة الذي اخترته أثناء الإعداد لـ applicationId. يمكنك من الناحية الفنية تبديل السمتَين بشكل مستقل من ذلك الحين فصاعدًا، ولكن لا يُنصح بذلك.

ننصحك باتّباع الخطوات التالية عند ضبط رقم تعريف التطبيق:

  • يجب أن يكون رقم تعريف التطبيق مطابقًا لمساحة الاسم. قد يكون الفرق بين السمتَين مربكًا بعض الشيء، ولكن إذا أبقيتهما متطابقتَين، لن تواجه أي مشكلة.
  • لا تغيِّر معرّف التطبيق بعد نشره، وإلا سيتعامل معه "متجر Google Play" على أنّه تطبيق جديد عند تحميله في المرة التالية.
  • حدِّد معرّف التطبيق بشكل صريح. إذا لم يتم تحديد معرّف التطبيق بشكل صريح باستخدام السمة applicationId، فإنه يأخذ تلقائيًا القيمة نفسها لمساحة الاسم. وهذا يعني أنّ تغيير مساحة الاسم يؤدي إلى تغيير معرّف التطبيق، وهو ما لا تريده عادةً.

تغيير معرّف التطبيق للاختبار

تطبّق أدوات الإنشاء تلقائيًا معرّف تطبيق على حزمة APK الخاصة بـ اختبار لقياس حالة التطبيق باستخدام معرّف التطبيق لتنويعة التصميم المحدّدة المُلحق بها .test. على سبيل المثال، حزمة APK الاختبارية لتنويعة التصميم com.example.myapp.free لها معرّف التطبيق com.example.myapp.free.test.

على الرغم من أنّ ذلك ليس ضروريًا، يمكنك تغيير معرّف التطبيق من خلال تحديد السمة testApplicationId في مجموعة defaultConfig أو productFlavor.

ضبط مساحة الاسم

تحتوي كل وحدة Android على مساحة اسم، والتي يتم استخدامها كاسم حزمة Kotlin أو Java لفئات R وBuildConfig التي تم إنشاؤها.

يتم تحديد مساحة الاسم من خلال السمة namespace في ملف build.gradle.kts الخاص بالوحدة، كما هو موضّح في مقتطف الرمز التالي. يتم ضبط namespace في البداية على اسم الحزمة الذي تختاره عند إنشاء مشروعك.

Kotlin

android {
    namespace = "com.example.myapp"
    ...
}

أنيق

android {
    namespace "com.example.myapp"
    ...
}

أثناء إنشاء تطبيقك في حزمة التطبيق النهائية (APK)، تستخدم أدوات إنشاء Android مساحة الاسم كمساحة اسم لفئة R التي تم إنشاؤها في تطبيقك، والتي تُستخدم للوصول إلى موارد تطبيقك. على سبيل المثال، في ملف الإصدار السابق، يتم إنشاء الفئة R في com.example.myapp.R.

يجب أن يتطابق الاسم الذي تحدّده لسمة namespace في ملف build.gradle.kts دائمًا مع اسم الحزمة الأساسية لمشروعك، حيث تحتفظ بالأنشطة ورموز التطبيقات الأخرى. يمكنك استخدام حزم فرعية أخرى في مشروعك، ولكن يجب أن تستورد هذه الملفات فئة R باستخدام مساحة الاسم من السمة namespace.

لتبسيط سير العمل، اجعل مساحة الاسم مماثلة لمعرّف التطبيق، كما هو الحال تلقائيًا.

تغيير مساحة الاسم

في معظم الحالات، يجب الإبقاء على مساحة الاسم ومعرّف التطبيق كما هما، كما هو الحال تلقائيًا. ومع ذلك، قد تحتاج إلى تغيير مساحة الاسم في مرحلة ما إذا كنت تعيد تنظيم الرمز الخاص بك أو لتجنب تعارض مساحة الاسم.

في هذه الحالات، يمكنك تغيير مساحة الاسم من خلال تعديل السمة namespace في ملف build.gradle.kts الخاص بالوحدة بشكل مستقل عن معرّف التطبيق. قبل إجراء ذلك، تأكَّد من تحديد معرّف التطبيق بشكل صريح، حتى لا يؤدي تغيير مساحة الاسم إلى تغيير معرّف التطبيق أيضًا. لمزيد من المعلومات حول كيفية تأثير مساحة الاسم في معرّف التطبيق، يُرجى الاطّلاع على ضبط معرّف التطبيق.

إذا كانت لديك أسماء مختلفة لـ namespace وGradle applicationId، تنسخ أدوات الإنشاء رقم تعريف التطبيق في ملف البيان النهائي لتطبيقك في نهاية عملية الإنشاء. لذا، إذا فحصت ملف AndroidManifest.xml بعد عملية الإنشاء، سيتم ضبط سمة package على معرّف التطبيق. سمة package في ملفات البيان المدمجة هي المكان الذي يبحث فيه "متجر Google Play" ونظام Android الأساسي لتحديد تطبيقك.

تغيير مساحة الاسم للاختبار

مساحة الاسم التلقائية لمجموعتَي رموز المصدر androidTest وtest هي مساحة الاسم الرئيسية، مع إضافة .test في النهاية. على سبيل المثال، إذا كانت السمة namespace في ملف build.gradle هي com.example.myapp، يتم ضبط مساحة الاسم الخاصة بالاختبار تلقائيًا على com.example.myapp.test. لتغيير مساحة الاسم للاختبار، استخدِم السمة testNamespace، كما هو موضّح في مقتطف الرمز التالي:

Kotlin

android {
    namespace = "com.example.myapp"
    testNamespace = "com.example.mytestapp"
    ...
}

أنيق

android {
    namespace "com.example.myapp"
    testNamespace "com.example.mytestapp"
    ...
}

لمزيد من المعلومات حول الاختبار، يُرجى الاطّلاع على مقالة اختبار التطبيقات على Android.