ملف إيضاح التطبيق

الإعلانات

نظرة عامه على ملف إيضاح التطبيق

 

 

ملف إيضاح التطبيق

كل مشروع تطبيق يجب أن يحتوي على ملف إيضاح AndroidManifest.xml (يحمل هذا الأسم بدقة تامه) في مجموعة مصادر المشروع الأساسية.

يشرح ملف إيضاح التطبيق معلومات أساسية عن تطبيقك لأدوات بناء الأندرويد ونظام تشغيل الأندرويد و سوق قوقل Google Play.

 

من بين عدة أشياء أخرى، مطلوب من ملف إيضاح التطبيق أن يعلن عن التالي:

 

اسم حزمة التطبيق، والتي تطابق عادة اسم نطاق الكود الخاص بك. أدوات بناء الأندرويد تستخدم هذا الاسم لتحديد موقع كيانات الكود عند بناء مشروعك.

عند حزم التطبيق، تقوم أدوات البناء بإستبدال هذه القيمة بمعرف التطبيق من ملفات بناء الـGradle، والتي تستخدم كمعرف فريد

للتطبيق على النظام وعلى السوق. اقرأ المزيد حول اسم الحزمة و معرف التطبيق.

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

يحدد الخصائص الأساسية مثل، اسم فئته سواء كانت جافا أو كوتلن.

يمكنه أيضاً الإعلان عن القدرات مثل تكوينات الجهاز التي يمكنه التعامل معها، ومرشحات الأغراض التي تصف كيفية بدء المكون. اقرأ المزيد عن مكونات التطبيق.

الأذونات التي يحتاجها التطبيق للوصول إلى الأجزاء المحمية من النظام أو إلى التطبيقات الأخرى.

 

كما يعلن أيضاً عن أي أذونات يجب أن توفرها التطبيقات الأخرى إذا أرادت الوصول إلى محتوى من هذا التطبيق. اقرأ المزيد عن الأذونات.

ميزات الجهاز والبرامج التي يتطلبها التطبيق، التي تؤثر على تحديد الأجهزة التي يمكنها تحميل التطبيق من السوق. اقرأ المزيد حول توافق الجهاز.

إذا كنت تستخدم الأندرويد ستوديو لبناء تطبيقك، فسيتم إنشاء ملف الإيضاح نيابة عنك، وستتم إضافة معظم عناصر الإيضاح

الأساسية أثناء إنشاءك للتطبيق (خاصة عند استخدام قوالب الكود).

 

 

مميزات الملف


تصف الأقسام التاليه كيفية تأثير بعض أهم خصائص تطبيقك على ملف الإيضاح.

 

اسم الحزمة ومعرف التطبيق

العنصر الأساسي لملف الإيضاح يتطلب سمة لأسم حزمة تطبيقك (عادة تطابق بنية مجلد المشروع – نطاق الجافا).

مثال، الجزء التالي يعرض عنصر الإيضاح الأساسي <manifest> مع اسم الحزمة "com.example.myapp":

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp"
    android:versionCode="1"
    android:versionName="1.0" >
    ...
</manifest>

 

أثناء إنشاء تطبيقك في حزمة التطبيق النهائية (APK)، تستخدم أدوات إنشاء الأندرويد سمة الحزمة لأمرين:

– يطبق هذا الأسم كنطاق لفئة المصادر R.java التي تم إنشاؤها لتطبيقك (تستخدم للوصول إلى مصادر تطبيقك).

مثال: في الإيضاح أعلاه، الفئة R تم إنشاؤها في com.example.myapp.R.

– يستخدم هذا الأسم لحل أي أسماء لفئات نسبية والتي تم الإعلان عنها في ملف الإيضاح.

مثال: في الإيضاح أعلاه، نشاط تم الإعلان عنه كـ<activity android:name=".MainActivity">. وهو مصمم ليكون com.example.myapp.MainActivity.

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

بالطبع، يمكن أن يكون لديك حزم فرعية أخرى في مشروعك، ولكن يجب أن تقوم هذه الملفات بإستيراد فئة R.java بإستخدام النطاق من سمة الحزمه package.

رغم ذلك، كن حذراً حالماً يتم تجميع ملف APK، تمثل سمة الحزمة أيضاً معرف تطبيقك الفريد عالمياً. بعد تنفيذ أدوات البناء المهام المذكورة أعلاه.

بناءً على اسم الحزمة، يتم إستبدال قيمة الحزمة بالقيمة المعطاه لخاصية معرف التطبيق في ملف مشروعك build.gradle (يستخدم في مشاريع أندرويد ستوديو).

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

الفرق بين اسم الحزمة package في ملف الإيضاح و معرف التطبيق applicationId في ملف build.gradle يمكن أن يكون مربكاً قليلاً. ولكن إذا ابقيتهم متشابهين، فليس لديك ما يدعو للقلق.

مع ذلك، إذا قررت إنشاء نطاق الكود الخاص بك (وبالتالي، اسم الحزمة في ملف الإيضاح) شيء مختلف عن معرف التطبيق من ملف البناء، تأكد من فهمك الكامل للآثار المترتبة على ضبط معرف التطبيق.

هذه الصفحة تشرح كيف يمكنك بأمان ضبط اسم حزمة الإيضاح بشكل مستقل عن معرف التطبيق الخاص بملف البناء، وتغيير معرف التتطبيق لتكوينات بناء مختلفة.

 

 

 

مكونات التطبيق


لكل مكون تطبيق تقوم بإنشائه في تطبيقك، يجب عليك تعريف عنصر XML المتطابق في ملف الإيضاح: ملف إيضاح التطبيق ملف إيضاح التطبيق ملف إيضاح التطبيق

<activity> لكل فئة فرعية من Activity

<service> لكل فئة فرعية من Service

<receiver> لكل فئة فرعية من BroadcastReceiver

<provider> لكل فئة فرعية من ContentProvider

إذا قمت بتفريع فئات أي من هذه المكونات، دون الإعلان عنها في ملف الإيضاح، لا يمكن أن يقوم النظام بتشغيلها.

اسم فئتك الفرعية يجب أن يتم تخصيصه بسمة الاسم، بإستخدام تسمية الحزمة الكاملة. مثال، الفئة الفرعية للنشاط يمكن الإعلان عنها كما يلي:

<manifest ... >
    <application ... >
        <activity android:name="com.example.myapp.MainActivity" ... >
        </activity>
    </application>
</manifest>

 

مع ذلك، إذا كان الحرف الأول في قيمة الاسم هو نقطه “.“، يكون اسم حزمة التطبيق ( من سمة حزمة لعنصر <manifest>) هو

بادئة الاسم. مثال، اسم النشاط التالي يحل إلى "com.example.myapp.MainActivity":

<manifest package="com.example.myapp" ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

 

إذا كان لديك محتويات تطبيق بداخل حزمة فرعية (مثال، com.example.myapp.purchases)، فإن قيمة الاسم يجب أن تضيف أسماء الحزم الفرعية المفقودة مثل (“.purchases.PayActivity“) أو تستخدم اسم الحزمة المؤهل بالكامل.

مرشحات الأغراض

أنشطة التطبيق، الخدمات، مستقبلات البث يتم تنشيطها بواسطة الأغراض. الغرض عبارة عن رسالة يتم تعريفها بواسطة كائن غرض يصف إجراء يجب تنفيذه.

بما في ذلك البيانات التي يتعين إتخاذ إجراءات بشأنها، صنف category المكون  الذي يجب أن ينفذ الإجراء، والإرشادات الأخرى.

عندما يصدر أحد التطبيقات غرض للنظام، يحدد النظام مكون التطبيق الذي يمكنه التعامل مع هذا الغرض.

بناءً على مرشح الغرض المعلن عنه في كل ملف إيضاح للتطبيق. يطلق النظام طلباً للمكون المناسب ويقوم بتمرير كائن الغرض إلى ذلك المكون.

إذا كان هناك أكثر من تطبيق يمكنه التعامل مع الغرض، عندها يمكن للمستخدم إختيار التطبيق المراد إستخدامه.

محتوى التطبيق يمكن أن يحتوي على أي عدد من مرشحات الأغراض ( محددة في عنصر <intent-filter>) كلٍ منها يصف قدرة مختلفة لهذا المكون.

لمزيد من المعلومات، راجع وثائق الغرض و مرشحات الغرض.

 

 

 

الأيقونات والمسميات

يحتوي عدد من عناصر الإيضاح على سمات أيقونات ومسميات لعرض أيقونات صغيرة و مسميات نص، للمستخدمين على التوالي، لمكون التطبيق المناسب.

في كل حالة، الأيقونة والمسمى الذين تم تعيينهما في العنصر الأصل تصبحان القيم الإفتراضية للأيقونة و المسمى لجميع العناصر التابعه.

مثال، الأيقونة والمسمى الذين تم تعيينهما في عنصر <application> هما الأيقونة والمسمى الإفتراضيان لكل مكونات التطبيق (مثلاً جميع الأنشطة).

الأيقونة والمسمى الذين تم تعيينهما لأحد مكونات <intent-filter> يتم عرضهم للمستخدم كلما تم تقديم ذلك المكون كخيار لتنفيذ غرض ما.

بشكلٍ إفتراضي، يتم توريث هذه الأيقونة من أي أيقونة تم إعلانها للمكون الأصلي (إما عنصر <activity> أو عنصر <application>).

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

 

 

الأذونات


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

يتم تعريف كل إذا بمسمى فريد. مثال، تطبيق يريد إرسال رسائل نصية يحتاج إلى الأسطر التاليه في ملف الإيضاح:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

 

بدءاً من أندرويد 6.0 (API 23)، يمكن للمستخدم الموافقة أو رفض بعض أذونات التطبيق أثناء وقت التشغيل. 

ولكن بغض النظر عن إصدار الأندرويد الذي يدعمه تطبيقك، يجب عليك الإعلان عن جميع طلبات الأذونات في عنصر <uses-permission> في ملف الإيضاح.

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

يمكن لتطبيقك أيضاً حماية مكوناته الخاصة بالأذونات، يمكنه إستخدام أياً من الأذونات التي يحددها الأندرويد.

كما هو موضح في أذونات ملف إيضاح الأندرويد android.Manifest.permission، أو الأذن المعلن عنها في تطبيق آخر.

يمكن لتطبيقك أيضاً تحديد أذوناته الخاصه. يتم الإعلان عن الأذن الجديدة بإستخدام العنصر <permission>.

لمزيد من المعلومات، راجع نظرة عامة على الأذونات.

 

 

 

توافق الجهاز


ملف الإيضاح، هو أيضاً المكان الذي يمكنك أن تعلن فيه، عن أدوات الأجهزة أو ميزات البرامج التي يتطلبها تطبيقك.

بالتالي، نوع الأجهزة التي يتوافق معها تطبيقك.

لا يسمح سوق قوقل بتثبيت تطبيقك على الأجهزة التي لا تتوفر بها المميزات أو إصدار النظام الذي يتطلبه تطبيقك.

هناك العديد من وسوم الإيضاح التي تحدد الأجهزة التي يتوافق معها تطبيقك. فيما يلي بعضاً من الوسوم الأكثر شيوعاً.

 

وسم <uses-feature>

يسمح لك عنصر <uses-feature> بالإعلان عن أدوات الجهاز و البرامج التي يحتاجها تطبيقك.

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

يمكنك الإعلان عن مستشعر البوصلة كما هو مطلوب بإستخدام وسم الإيضاح التالي:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

 

ملاحظة: إذا كنت تريد جعل تطبيقك متاحاً على أجهزة كرومبوكس Chromebooks، فهناك بعض القيود الهامة للأدوات والبرامج التي يجب عليك مراعاتها. لمزيد من المعلومات، راجع توافق إيضاح التطبيق مع أجهزة كرومبوكس.

وسم <uses-sdk>

كل إصدار أساسي تالي للنظام يقوم بإضافة برمجيات واجهة مستخدم جديدة لم تكن متوفرة في الإصدار السابق.

للإشارة إلى أدنى إصدار يتوافق مع تطبيقك، يجب أن يحتوي الإيضاح على الوسم <uses-sdk> وسمته minSdkVersion.

مع ذلك، تنبه أن سمات العنصر <uses-sdk> يتم تجاهلها بواسطة خصائص التوافق في ملف build.gradle.

لذا إن كنت تستخدم أندرويد ستوديو يجب أن تقوم بتحديد قيم minSdkVersion و targetSdkVersion هناك بدلاً من ذلك:

android {
  defaultConfig {
    applicationId 'com.example.myapp'

    // Defines the minimum API level required to run the app.
    minSdkVersion 15

    // Specifies the API level used to test the app.
    targetSdkVersion 28

    ...
  }
}

 

لمزيد من المعلومات عن ملف build.gradle، اقرأ عن كيفية تكوين بنيتك.

لمعرفة المزيد عن كيفية الإعلان عن دعم تطبيقك للأجهزة المختلفة، راجع نظرة عامة على توافق الجهاز.

 

 

إتفاقيات الملف


يصف هذا القسم الإتفاقيات والقواعد التي تنطبق عموماً على جميع العناصر والسمات في ملف الإيضاح.

 

العناصر

فقط عناصر <manifest> و <application> هي المطلوبه. كلٍ منهما يجب أن تحدث مرة واحدة فقط.

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

جميع القيم يتم تعيينها خلال السمات، ليس كبيانات أحرف بداخل العنصر.

بشكلٍ عام لا يتم طلب العناصر الموجودة في نفس المستوى. مثال، عناصر

<activity>  ،<provider> , و <service> يمكن أن توضع بأي ترتيب. هناك إستثناءان رئيسيان لهذه القاعدة:

السمات

تقنياً، كل السمات إختياريه، مع ذلك، يجب أن يتم تحديد العديد من السمات، بحيث يمكن لبعض العناصر إنجاز أهدافها.

بالنسبة للسمات الإختياريه الحقيقيه، تشير الوثائق المرجعية إلى القيم الافتراضية.

بإستثناء بعض سمات العنصر الأساسي <manifest> ، جميع أسماء السمات تبدأ بـ android:. مثال، android:alwaysRetainTaskState.

لأن البادئة عامه، عادة ما تقوم الوثائق بحذفها، عند الإشارة إلى السمات بواسطة الأسماء.

 

القيم المتعددة

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

<intent-filter ... >
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.INSERT" />
    <action android:name="android.intent.action.DELETE" />
    ...
</intent-filter>

 

 

قيم المصادر

بعض السمات تحتوي على قيم يتم عرضها للمستخدمين، مثل عنوان نشاط ما أو أيقونة تطبيقك.

قيم هذه السمات، قد تختلف بناءً على لغة المستخدم، أو التكوينات الأخرى للجهاز (مثل، توفير أيقونة بحجم مختلف بناءً على كثافة بكسلات الجهاز).

لذا يجب تعيين القيم من مصدر أو ثيم، بدلاً من تشفيرها (برمجتها) في ملف الإيضاح.

يمكن بعد ذلك، تغيير القيمة الفعليه، بناءً على المصادر البديلة التي تقوم بتوفيرها للتكوينات المختلفة للجهاز.

 

 

يتم التعبير عن المصادر كقيم بالشكل التالي:

package:]type/name]@

يمكنك حذف اسم الحزمة، إذا تم توفير المصدر بواسطة تطبيقك (بما في ذلك ما إذا كان يتم توفيره، بواسطة مكتبة تابعه، لأن مصادر المكتبة مدمجة في تطبيقك).

اسم الحزمة الآخر الوحيد الصالح هو android، عندما ترغب بإستخدام، مصدر من إطار عمل الأندرويد.

النوع هو نوع من المصدر، مثل سلسلة أو رسوميات، والاسم هو الاسم الذي يميز المصدر المحدد. إليك مثال:

لمزيد من المعلومات حول كيفية إضافة المصادر إلى مشروعك، اقرأ توفير المصادر.

بدلاً من تطبيق قيمة محددة على ثيم، يجب أن يكون أول حرف “؟” بدلاً من “@“:

package:]type/name]?

 

 

قيم السلاسل 

عندما تكون قيمة السمه عبارة عن سلسلة، يجب أن تستخدم شرطتين مائلتين (\\) لتخطي الأحرف، مثل \\n لإضافة سطر جديد أو \\uxxxx لحروف اليونيكود (الترميز الموحد).

 

 

 

الإشارة إلى عناصر الإيضاح


يوفر الجدول التالي روابط للمستندات المرجعية لكافة العناصر الصالحة في ملف الإيضاح AndroidManifest.xml:

<action>  يضيف إجراء إلى مرشح الغرض
<activity>  يعلن عن مكون النشاط
<activity-alias>  يعلن عن اسم مستعار للنشاط
<application>  إعلان عن التطبيق
<category>  يضيف اسم فئة إلى مرشح الغرض
<compatible-screens>  يحدد أي تكوين للشاشة يتوافق مع التطبيق
<data>  يضيف بيانات مخصصه إلى مرشح الغرض
<grant-uri-permission>  يحدد المجموعة الفرعية من بيانات التطبيق التي يملك موفر المحتوى الرئيسي إذن للوصول إليها.
<instrumentation>  تعلن عن فئة الأجهزة التي تمكنك من مراقبة تفاعل التطبيق مع النظام
<intent-filter>  يحدد أنواع الأغراص التي يمكن أن يستجيب لها النشاط أو الخدمة أو مستقبل البث
<manifest>  العنصر الأساسي لملف AndroidManifest.xml
<meta-data>  زوج “اسم-قيمه” لعنصر إضافي، بيانات عشوائيه يمكن توفيرها للمكون الرئيسي
<path-permission>  يحدد المسار والأذونات المطلوبة لمجموعة فرعية محددة من البيانات داخل موفر المحتوى
<permission>  يعلن عن إذن أمان يمكن إستخدامها لتقييد الوصول إلى مكونات أو ميزات معينة من هذا التطبيق أو من التطبيقات الأخرى
<permission-group> يعلن عن اسم لتجمع منطقي للأذونات ذات الصله
<permission-tree> يعلن عن الاسم الأساسي لشجرة الأذونات
<provider> يعلن عن مكون موفر المحتوى
<receiver> يعلن عن مكون مستقبل البث
<service> يعلن عن مكون الخدمه
<supports-gl-texture> يعلن عن صيغة بنية GL واحده، والتي يدعمها التطبيق
<supports-screens> يعلن عن أحجام الشاشات التي يدعمها تطبيقك، ويقوم بتمكين وضع توافق الشاشة، للشاشات ذات الحجم الأكبر عما يدعمه تطبيقك
<uses-configuration> يشير إلى ميزات إدخال محددة يتطلبها التطبيق
<uses-feature> يعلن عن خاصية واحدة للهاردير أو السوفتوير والتي يستخدمها التطبيق
<uses-library> يحدد مكتبة مشتركه والتي يجب ربط التطبيق بها
<uses-permission> يحدد إذن نظام يجب على المستخدم منحها لكي يعمل التطبيق بشكلٍ صحيح
<uses-permission-sdk-23> يحدد أن التطبيق يريد إذن معينه، ولكن فقط إن تم تثبيت التطبيق على جهاز يعمل بنظام أندرويد 6 (المستوى 23) أو أعلى
<uses-sdk> يتيح لك إمكانية توضيح أن تطبيق ما يتوافق مع إصدار واحد أو أكثر من إصدارات منصة الأندرويد، من خلال “رقم” مستوى واجهة برمجة التطبيقات API

 

 

 

مثال على ملف الإيضاح


ملف XML التالي هو مثال بسيط على ملف الإيضاح AndroidManifest.xml الذي يعلن عن نشاطين للتطبيق: ملف إيضاح التطبيق ملف إيضاح التطبيق ملف إيضاح التطبيق

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.example.myapp">

    <!-- Beware that these values are overridden by the build.gradle file -->
    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <!-- This name is resolved to com.example.myapp.MainActivity
             based upon the package attribute -->
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <activity
            android:name=".DisplayMessageActivity"
            android:parentActivityName=".MainActivity" />
    </application>
</manifest>

 

 


للإطلاع على المقال باللغة الإنجليزية أضغط هنا.

الإعلانات

19 thoughts on “ملف إيضاح التطبيق”

اترك رد