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

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

من بين أمور أخرى كثيرة، يجب تقديم ملف البيان للإشارة إلى ما يلي:

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

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

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

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

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

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

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

حدِّد اسم فئتك الفرعية باستخدام السمة 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.

في المقابل، إنّ السمات المقابلة في ملف 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>