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

يجب أن يحتوي كل مشروع تطبيق على ملف 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 نقطة، تتم إضافة مساحة اسم التطبيق، من السمة 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>.

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

الأذونات

يجب أن تطلب تطبيقات 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.

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

Groovy

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

الحدود

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

اسم العلامة	الحد اليومي
<package>	1000
<meta-data>	1000
<uses-library>	1000

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

السمة	الحد اليومي
name	1024
versionName	1024
host	255
mimeType	255

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

إنّ 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>