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

يجب أن يتضمّن كل مشروع تطبيق ملف 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 استنادًا إلى بيانات intent filter في ملف بيان كل تطبيق. يطلق النظام مثيلاً للمكوّن المطابق ويمرّر كائن Intent إلى ذلك المكوّن. إذا كان بإمكان أكثر من تطبيق واحد التعامل مع الغرض، يمكن للمستخدم اختيار التطبيق الذي يريد استخدامه.

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

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

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

يحتوي عدد من عناصر البيان على السمتَين 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 هناك بدلاً من ذلك:

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

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

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

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

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

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

لمزيد من المعلومات حول ملف build.gradle، يمكنك الاطّلاع على كيفية ضبط عملية الإنشاء.

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

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

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

العناصر

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

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

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

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

السمات

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

باستثناء بعض سمات عنصر الجذر <manifest>، تبدأ جميع أسماء السمات بالبادئة android:، مثل android:alwaysRetainTaskState. بما أنّ البادئة عامة، يتم حذفها عادةً في المستندات عند الإشارة إلى السمات بالاسم.

قيم متعدّدة

إذا كان من الممكن تحديد أكثر من قيمة واحدة، يتم تكرار العنصر دائمًا تقريبًا، بدلاً من إدراج قيم متعددة ضمن عنصر واحد. على سبيل المثال، يمكن أن يعرض intent filter عدة إجراءات:

<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>