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

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

من بين العديد من الإجراءات الأخرى، يجب أن يوضّح ملف البيان ما يلي:

• يتضمن التطبيق مكونات التطبيق، بما في ذلك جميع الأنشطة والخدمات وأجهزة استقبال البث ومزودي المحتوى. يجب أن يحدِّد كل مكوّن خصائص dasar ، مثل اسم فئة 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>

قد تحتاج إلى تغيير رمز فلتر الأهداف إذا كان يقدّم إجراءً فريدًا تريد الإشارة إليه بشكل أفضل في مربع 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 من القيم هناك بدلاً من ذلك:

رائع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
        ...
    }
}

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.

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