يجب أن يتضمّن كل مشروع تطبيق ملف 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
من القيم هناك بدلاً من ذلك:
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>