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

يجب أن يتضمّن كل مشروع تطبيق ملف 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> )، يصف كل عنصر قدرة مختلفة لهذا المكون.

لمزيد من المعلومات، راجع مستند أهداف وفلاتر الأهداف.

الأيقونات والتصنيفات

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

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

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

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

الأذونات

يجب أن تطلب تطبيقات 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 من القيم هناك بدلاً من ذلك:

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، يُرجى الاطّلاع على طريقة ضبط الإصدار.

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

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

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

Elements

فقط <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.

الحدود

هناك حد لعدد مرات الورود في ملف البيان للعلامات التالية:

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

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

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>