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

يجب أن يتضمّن كل مشروع تطبيق ملف 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> )، ويصف كل فلتر منها قدرة مختلفة لهذا المكوّن.

لمزيد من المعلومات، راجع مستند أهداف وفلاتر الأهداف.

الأيقونات والتصنيفات

يتضمن عدد من عناصر البيان السمتَين 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>