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

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

من بين أمور أخرى كثيرة، يجب أن يتضمّن ملف البيان ما يلي:

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

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

ميزات الملف

توضح الأقسام التالية كيفية انعكاس بعض أهم الخصائص لتطبيقك في ملف البيان.

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

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

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

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

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

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

ومع ذلك، إذا كان الحرف الأول في القيمة name نقطة، فإن مساحة اسم التطبيق، من خاصية build.gradle على مستوى الوحدة namespace، تبدأ ببادئة الاسم. على سبيل المثال، إذا كانت مساحة الاسم هي "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>)، ويصف كل مكوّن منها قدرة مختلفة من هذا المكوِّن.

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

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

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

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

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

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

الأذونات

يجب أن تطلب تطبيقات Android إذنًا للوصول إلى بيانات المستخدم الحساسة، مثل جهات الاتصال والرسائل القصيرة، أو بعض ميزات النظام، مثل الكاميرا والوصول إلى الإنترنت. ويتم تحديد كل إذن من خلال تصنيف فريد. على سبيل المثال، يجب أن يحتوي التطبيق الذي يحتاج إلى إرسال رسائل 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 الخاصة بها.

مع ذلك، تجدر الإشارة إلى أنّ السمات المقابلة في ملف build.gradle تلغي السمات في العنصر <uses-sdk>. لذلك، إذا كنت تستخدم "استوديو 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
        ...
    }
}

Kotlin

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لحرف Unicode.

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

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

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

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

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