نظرة عامة على بيان التطبيق

يجب أن يتضمّن كل مشروع تطبيق ملف AndroidManifest.xml يحمل اسمًا بالضبط مماثلاً لملف AndroidManifest.xml في جذر مجموعة مصادر المشروع. يوضّح ملف البيان المعلومات الأساسية حول تطبيقك لأدوات إنشاء Android ونظام التشغيل Android و Google Play.

من بين العديد من الإجراءات الأخرى، يجب أن يوضّح ملف البيان ما يلي:

• مكونات التطبيق، بما في ذلك جميع الأنشطة والخدمات وأجهزة استقبال البث ومقدّمي المحتوى يجب أن يحدِّد كل مكوّن خصائص dasar ، مثل اسم فئة Kotlin أو Java. ويمكنه أيضًا تحديد الإمكانات، مثل إعدادات الجهاز التي يمكنه التعامل معها، و فلاتر الأهداف التي تصف كيفية بدء المكوّن. اطّلِع على مزيد من المعلومات عن مكوّنات التطبيق في قسم لاحق.
• الأذونات التي يحتاجها التطبيق للوصول إلى أجزاء محمية من النظام أو التطبيقات الأخرى ويوضّح البيان أيضًا أي أذونات يجب أن تحصل عليها التطبيقات الأخرى إذا أرادت الوصول إلى المحتوى من هذا التطبيق. اطّلِع على مزيد من المعلومات عن الأذونات في القسم التالي.
• ميزات الأجهزة والبرامج التي يتطلبها التطبيق، ما يؤثر في الأجهزة التي يمكنها تثبيت التطبيق من Google Play اطّلِع على مزيد من المعلومات عن توافق الأجهزة في القسم التالي.

إذا كنت تستخدِم Android Studio لإنشاء تطبيقك، سيتم إنشاء ملف البيان نيابةً عنك وستتم إضافة معظم عناصر البيان الأساسية أثناء إنشاء تطبيقك، خاصةً عند استخدام نماذج الرموز البرمجية.

ميزات الملفات

توضّح الأقسام التالية كيفية ظهور بعض أهم سمات تطبيقك في ملف البيان.

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

لكل أحد مكونات التطبيق التي تنشئها في تطبيقك، حدِّد عنصر XML متوافقًا في ملف البيان:

• <activity> لكل فئة فرعية من Activity
• <service> لكل فئة فرعية من Service
• <receiver> لكل فئة فرعية من BroadcastReceiver
• <provider> لكل فئة فرعية من ContentProvider

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

حدِّد اسم الفئة الفرعية باستخدام السمة name ، مع استخدام تصنيف الحزمة الكامل. على سبيل المثال، يتمّ الإعلان عن فئة فرعية Activity على النحو التالي:

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

ومع ذلك، إذا كان الحرف الأول في قيمة name هو نقطة، يتم إضافة مساحة الاسم للتطبيق، من سمة namespace ملف build.gradle على مستوى الوحدة، إلى الاسم. على سبيل المثال، إذا كانت مساحة الاسم هي "com.example.myapp"، يتم تحويل اسم النشاط التالي إلى com.example.myapp.MainActivity:

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

لمزيد من المعلومات عن ضبط اسم الحزمة أو مساحة الاسم، اطّلِع على ضبط مساحة الاسم.

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

فلاتر الأهداف

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

عندما يُرسِل تطبيق هدفًا إلى النظام، يحدِّد النظام موقع ملف بيان تطبيق يمكنه معالجة الهدف استنادًا إلى فلتر الأهداف في ملف بيان كل تطبيق. يطلق النظام مثيلًا للمكوّن المطابق ويمرّر عنصر Intent إلى هذا المكوّن. إذا كان بإمكان أكثر من تطبيق معالجة الطلب، يمكن للمستخدم اختيار التطبيق الذي يريد استخدامه.

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستند Intents and Intent Filters (النوايا وفلاتر النوايا).

الرموز والتصنيفات

تحتوي مجموعة من عناصر البيان على السمتَين icon وlabel لعرض رمز صغير وتصنيف نصي، على التوالي، للمستخدمين لعنصر التطبيق المقابل.

في كل الحالات، يصبح الرمز والاسم اللذان تم ضبطهما في عنصر رئيسي هما القيمة التلقائية icon وlabel لجميع العناصر الفرعية. على سبيل المثال، الرمز والتصنيف اللذان تم ضبطهما في عنصر <application> هما الرمز والتصنيف التلقائيان لكل مكوّن من مكوّنات التطبيق، مثل جميع الأنشطة.

يتم عرض الرمز والتصنيف اللذان تم ضبطهما في <intent-filter> المكوّن للمستخدم كلما تم عرض هذا المكوّن كخيار ل تحقيق نية. يتم اكتساب هذا الرمز تلقائيًا من أي رمز يتم تحديده للمكوّن الرئيسي، سواء كان عنصر <activity> أو <application>.

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

الأذونات

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

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

بدءًا من الإصدار Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات)، يمكن للمستخدم الموافقة على بعض أذونات التطبيق أو رفضها أثناء التشغيل. ولكن بغض النظر عن إصدار Android الذي يتوافق معه تطبيقك، يجب الإفصاح عن جميع طلبات الأذونات باستخدام عنصر <uses-permission> في البيان. في حال منح الإذن، سيتمكّن التطبيق من استخدام الميزات المحمية. وإذا لم يكن الأمر كذلك، ستتعذّر محاولات الوصول إلى هذه الميزات.

يمكن لتطبيقك أيضًا حماية مكوّناته باستخدام الأذونات. ويمكنه استخدام أي من الأذونات التي يحدّدها نظام التشغيل Android، كما هو موضّح في android.Manifest.permission، أو إذن تم الإفصاح عنه في تطبيق آخر. ويمكن لتطبيقك أيضًا تحديد أذوناته الخاصة. يتمّ الإعلان عن إذن جديد باستخدام العنصر <permission>.

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

توافق الجهاز

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

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

<uses-feature>

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

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

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

<uses-sdk>

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

ومع ذلك، يُرجى العِلم أنّ السمات في عنصر <uses-sdk> يتم إلغاؤها من خلال السمات المقابلة في ملف build.gradle. لذلك، إذا كنت تستخدم "استوديو Android"، حدِّد قيمتَي minSdkVersion و targetSdkVersion هناك بدلاً من ذلك:

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

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

        // Specifies the API level used to test the app.
        targetSdkVersion 33
        ...
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(21)

        // Specifies the API level used to test the app.
        targetSdkVersion(33)
        ...
    }
}

لمزيد من المعلومات عن ملف build.gradle، اطّلِع على كيفية ضبط الإصدار.

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

اصطلاحات الملفات

يصف هذا القسم القواعد والاصطلاحات التي تنطبق بشكل عام على كل العناصر والسمات في ملف البيان.

العناصر

يجب استخدام العنصرين <manifest> و <application> فقط. ويجب أن يظهر كلّ منها مرّة واحدة فقط. يمكن أن لا تظهر معظم العناصر الأخرى أو تظهر مرّة واحدة أو أكثر. ومع ذلك، يجب أن يكون بعض هذه العناصر متوفّرًا لجعل ملف البيان مفيدًا.

يتمّ ضبط جميع القيم من خلال السمات، وليس كبيانات أحرف ضمن عنصر.

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

• يجب أن يتبع عنصر <activity-alias> عنصر <activity> الذي يمثّل بديلاً له.
• يجب أن يكون عنصر <application> هو العنصر الأخير داخل عنصر <manifest>.

السمات

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

باستثناء بعض سمات العنصر الجذر <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"

يمكنك حذف اسم package إذا كان المورد مقدَّمًا من تطبيقك (بما في ذلك إذا كان مقدَّمًا من مكتبة تابعة، لأنّ موارد المكتبة تُدمج في مواردك). اسم الحزمة الصالح الوحيد الآخر هو android، وذلك عندما تريد استخدام مورد من إطار عمل Android.

يشير الرمز type إلى نوع المورد، مثل string أو drawable، ويكون الرمز name هو الاسم الذي يحدّد المورد المحدّد. يُرجى الاطّلاع على المثال أدناه:

<activity android:icon="@drawable/smallPic" ... >

لمزيد من المعلومات عن كيفية إضافة موارد إلى مشروعك، يمكنك الاطّلاع على مقالة نظرة عامة على موارد التطبيق.

لتطبيق قيمة محدّدة في مظهر بدلاً من ذلك، يجب أن يكون الحرف الأول ? بدلاً من @:

"?[package:]type/name"

قيم السلاسل

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

مرجع عناصر البيان

يقدّم الجدول التالي روابط إلى المستندات المرجعية لجميع العناصر الصالحة في ملف AndroidManifest.xml.

الحدود

هناك حدّ أقصى لعدد مرات ظهور العلامات التالية في ملف البيان:

هناك حدّ أقصى لطول السمات التالية:

مثال على ملف البيان

ملف 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">

    <!-- 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 on the namespace property in the build.gradle file -->
        <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>