نمای کلی مانیفست برنامه

هر پروژه برنامه باید یک فایل AndroidManifest.xml ، دقیقاً با همین نام، در ریشه مجموعه منبع پروژه داشته باشد. فایل مانیفست اطلاعات ضروری در مورد برنامه شما را برای ابزارهای ساخت Android، سیستم عامل Android و Google Play توضیح می دهد.

در میان بسیاری از موارد دیگر، فایل مانیفست باید موارد زیر را اعلام کند:

• اجزای برنامه، شامل تمام فعالیت ها، خدمات، گیرنده های پخش و ارائه دهندگان محتوا. هر کامپوننت باید ویژگی های اساسی مانند نام کلاس Kotlin یا Java خود را تعریف کند. همچنین می‌تواند قابلیت‌هایی مانند پیکربندی‌های دستگاه را که می‌تواند مدیریت کند و فیلترهای هدف که نحوه راه‌اندازی مؤلفه را توضیح می‌دهند، اعلام کند. در بخش زیر درباره اجزای برنامه بیشتر بخوانید .
• مجوزهایی که برنامه برای دسترسی به بخش های محافظت شده سیستم یا سایر برنامه ها به آن نیاز دارد. همچنین هرگونه مجوزی را که سایر برنامه‌ها در صورت تمایل به دسترسی به محتوای این برنامه باید داشته باشند، اعلام می‌کند. اطلاعات بیشتر در مورد مجوزها را در بخش زیر بخوانید .
• ویژگی‌های سخت‌افزاری و نرم‌افزاری مورد نیاز برنامه، که بر دستگاه‌هایی که می‌توانند برنامه را از Google Play نصب کنند، تأثیر می‌گذارد. در بخش زیر درباره سازگاری دستگاه بیشتر بخوانید .

اگر از Android Studio برای ساختن برنامه خود استفاده می‌کنید، فایل مانیفست برای شما ایجاد می‌شود و اکثر عناصر ضروری مانیفست هنگام ساخت برنامه اضافه می‌شوند، مخصوصاً هنگام استفاده از الگوهای کد .

ویژگی های فایل

بخش‌های زیر توضیح می‌دهند که چگونه برخی از مهم‌ترین ویژگی‌های برنامه شما در فایل مانیفست منعکس می‌شوند.

اجزای برنامه

برای هر مؤلفه برنامه ای که در برنامه خود ایجاد می کنید، یک عنصر 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 برای سیستم صادر می کند، سیستم یک مؤلفه برنامه را پیدا می کند که می تواند هدف را بر اساس اعلامیه های فیلتر قصد در فایل مانیفست هر برنامه مدیریت کند. سیستم نمونه ای از مؤلفه تطبیق را راه اندازی می کند و شی Intent را به آن مؤلفه ارسال می کند. اگر بیش از یک برنامه بتواند این هدف را مدیریت کند، کاربر می‌تواند انتخاب کند که از کدام برنامه استفاده کند.

یک جزء برنامه می‌تواند هر تعداد فیلتر هدف داشته باشد (تعریف شده با عنصر <intent-filter> )، که هر کدام قابلیت متفاوتی از آن جزء را توصیف می‌کنند.

برای اطلاعات بیشتر، به سند Intent and Intent Filters مراجعه کنید.

نمادها و برچسب ها

تعدادی از عناصر مانیفست دارای ویژگی‌های icon و label برای نمایش یک نماد کوچک و یک برچسب متنی، به ترتیب، به کاربران برای مؤلفه برنامه مربوطه هستند.

در هر مورد، نماد و برچسبی که در یک عنصر والد تنظیم شده‌اند، icon و مقدار label پیش‌فرض برای همه عناصر فرزند می‌شوند. به عنوان مثال، نماد و برچسبی که در عنصر <application> تنظیم شده اند، نماد و برچسب پیش فرض برای هر یک از اجزای برنامه، مانند تمام فعالیت ها هستند.

نماد و برچسبی که در <intent-filter> یک مؤلفه تنظیم شده است، هر زمان که آن مؤلفه به عنوان گزینه ای برای انجام یک هدف ارائه شود، به کاربر نشان داده می شود. به‌طور پیش‌فرض، این نماد از هر نمادی که برای مؤلفه والد اعلان شده باشد، از عنصر <activity> یا <application> به ارث می‌رسد.

ممکن است بخواهید نماد یک فیلتر قصد را تغییر دهید، اگر یک عملکرد منحصر به فرد ارائه می دهد که می خواهید بهتر در گفتگوی انتخابگر نشان داده شود. برای اطلاعات بیشتر، به برنامه‌های دیگر اجازه دهید فعالیت شما را شروع کنند را ببینید.

مجوزها

برنامه‌های Android باید برای دسترسی به داده‌های حساس کاربر، مانند مخاطبین و پیامک‌ها یا برخی ویژگی‌های سیستم مانند دوربین و دسترسی به اینترنت، مجوز درخواست کنند. هر مجوز با یک برچسب منحصر به فرد مشخص می شود. برای مثال، اپلیکیشنی که نیاز به ارسال پیامک دارد، باید خط زیر را در مانیفست داشته باشد:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

با شروع Android 6.0 (سطح API 23)، کاربر می تواند برخی از مجوزهای برنامه را در زمان اجرا تأیید یا رد کند. اما مهم نیست که برنامه شما از کدام نسخه اندروید پشتیبانی می‌کند، باید همه درخواست‌های مجوز را با عنصر <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>

هر نسخه پلتفرم متوالی اغلب API های جدیدی را اضافه می کند که در نسخه قبلی موجود نیست. برای نشان دادن حداقل نسخه ای که برنامه شما با آن سازگار است، مانیفست شما باید دارای تگ <uses-sdk> و ویژگی minSdkVersion آن باشد.

با این حال، توجه داشته باشید که ویژگی‌های عنصر <uses-sdk> توسط ویژگی‌های مربوطه در فایل build.gradle لغو می‌شوند. بنابراین، اگر از Android Studio استفاده می‌کنید، مقادیر 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 ، درباره نحوه پیکربندی ساخت خود بخوانید.

برای کسب اطلاعات بیشتر درباره نحوه اعلام پشتیبانی برنامه از دستگاه‌های مختلف، به نمای کلی سازگاری دستگاه مراجعه کنید.

قراردادهای فایل

این بخش قراردادها و قوانینی را که عموماً برای همه عناصر و ویژگی‌های فایل مانیفست اعمال می‌شوند، توضیح می‌دهد.

عناصر

فقط عناصر <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 ارائه می دهد.

محدودیت ها

تگ های زیر محدودیتی در تعداد رخدادها در فایل مانیفست دارند:

ویژگی های زیر محدودیتی در حداکثر طول خود دارند:

فایل مانیفست نمونه

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>