ภาพรวมไฟล์ Manifest ของแอป

โปรเจ็กต์แอปทุกโปรเจ็กต์ต้องมีไฟล์ AndroidManifest.xml ที่มีชื่อดังกล่าวที่รูทของชุดแหล่งที่มาของโปรเจ็กต์ ไฟล์ Manifest จะอธิบายข้อมูลสำคัญเกี่ยวกับแอปของคุณให้กับเครื่องมือสร้าง Android, ระบบปฏิบัติการ Android และ Google Play

ไฟล์ Manifest ต้องประกาศข้อมูลต่อไปนี้ด้วย

• คอมโพเนนต์ของแอป ซึ่งรวมถึงกิจกรรม บริการ ผู้รับสัญญาณออกอากาศ และผู้ให้บริการเนื้อหาทั้งหมด คอมโพเนนต์แต่ละรายการต้องกำหนดพร็อพเพอร์ตี้พื้นฐาน เช่น ชื่อคลาส Kotlin หรือ Java นอกจากนี้ยังประกาศความสามารถต่างๆ ได้ เช่น การกำหนดค่าอุปกรณ์ที่จัดการได้ และตัวกรอง Intent ที่อธิบายวิธีเริ่มใช้งานคอมโพเนนต์ อ่านข้อมูลเพิ่มเติมเกี่ยวกับคอมโพเนนต์แอปในส่วนถัดไป
• สิทธิ์ที่แอปจําเป็นต้องใช้เพื่อเข้าถึงส่วนที่ได้รับการปกป้องของระบบหรือแอปอื่นๆ และยังประกาศสิทธิ์ทั้งหมดที่แอปอื่นๆ ต้องมีหากต้องการเข้าถึงเนื้อหาจากแอปนี้ อ่านเพิ่มเติมเกี่ยวกับสิทธิ์ในส่วนถัดไป
• ฟีเจอร์ฮาร์ดแวร์และซอฟต์แวร์ที่แอปต้องใช้ ซึ่งส่งผลต่ออุปกรณ์ที่ติดตั้งแอปจาก Google Play ได้ อ่านเพิ่มเติมเกี่ยวกับความเข้ากันได้ของอุปกรณ์ในส่วนถัดไป

หากคุณใช้ Android Studio เพื่อสร้างแอป ระบบจะสร้างไฟล์ Manifest ให้คุณและเพิ่มองค์ประกอบ Manifest ที่สำคัญส่วนใหญ่ขณะที่คุณสร้างแอป โดยเฉพาะเมื่อใช้เทมเพลตโค้ด

ฟีเจอร์ของไฟล์

ส่วนต่อไปนี้อธิบายลักษณะที่สำคัญที่สุดบางอย่างของแอปที่แสดงในไฟล์ Manifest

คอมโพเนนต์ของแอป

สําหรับคอมโพเนนต์แอปแต่ละรายการที่คุณสร้างในแอป ให้ประกาศองค์ประกอบ XML ที่เกี่ยวข้องในไฟล์ Manifest ดังนี้

• <activity> สำหรับคลาสย่อยแต่ละคลาสของ Activity
• <service> สำหรับคลาสย่อยแต่ละคลาสของ Service
• <receiver> สำหรับคลาสย่อยแต่ละคลาสของ BroadcastReceiver
• <provider> สำหรับคลาสย่อยแต่ละคลาสของ ContentProvider

หากคุณสร้างคลาสย่อยของคอมโพเนนต์เหล่านี้โดยไม่ประกาศในไฟล์ Manifest ระบบจะไม่สามารถเริ่มคอมโพเนนต์ดังกล่าวได้

ระบุชื่อของคลาสย่อยด้วยแอตทริบิวต์ 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 ไปยังระบบ ระบบจะค้นหาคอมโพเนนต์แอปที่จัดการ Intent ได้ โดยอิงตามประกาศตัวกรอง Intent ในไฟล์ Manifest ของแต่ละแอป ระบบจะเปิดใช้งานอินสแตนซ์ของคอมโพเนนต์ที่ตรงกันและส่งออบเจ็กต์ Intent ไปยังคอมโพเนนต์นั้น หากมีแอปมากกว่า 1 แอปที่จัดการ Intent ได้ ผู้ใช้จะเลือกแอปที่จะใช้ได้

คอมโพเนนต์แอปอาจมีตัวกรอง Intent กี่รายการก็ได้ (กำหนดด้วยองค์ประกอบ <intent-filter>) โดยแต่ละรายการจะอธิบายความสามารถที่แตกต่างกันของคอมโพเนนต์นั้น

ดูข้อมูลเพิ่มเติมได้ที่เอกสารIntent และตัวกรอง Intent

ไอคอนและป้ายกำกับ

เอลิเมนต์ไฟล์ Manifest บางรายการมีแอตทริบิวต์ icon และ label สำหรับแสดงไอคอนขนาดเล็กและป้ายกำกับข้อความต่อผู้ใช้สำหรับคอมโพเนนต์แอปที่เกี่ยวข้องตามลำดับ

ในทุกกรณี ไอคอนและป้ายกำกับที่ตั้งค่าไว้ในองค์ประกอบหลักจะเป็นค่าเริ่มต้นสำหรับ icon และ label ขององค์ประกอบย่อยทั้งหมด ตัวอย่างเช่น ไอคอนและป้ายกำกับที่ตั้งค่าไว้ในองค์ประกอบ <application> จะเป็นไอคอนและป้ายกำกับเริ่มต้นสำหรับคอมโพเนนต์แต่ละรายการของแอป เช่น กิจกรรมทั้งหมด

ไอคอนและป้ายกำกับที่ตั้งค่าไว้ใน <intent-filter> ของคอมโพเนนต์จะแสดงต่อผู้ใช้ทุกครั้งที่คอมโพเนนต์นั้นแสดงเป็นตัวเลือกเพื่อดำเนินการตาม Intent โดยค่าเริ่มต้น ไอคอนนี้จะรับค่ามาจากไอคอนที่ประกาศสำหรับคอมโพเนนต์หลัก ไม่ว่าจะเป็นองค์ประกอบ <activity> หรือ <application>

คุณอาจต้องเปลี่ยนไอคอนสำหรับตัวกรอง Intent หากมีการดำเนินการที่ไม่ซ้ำกันซึ่งคุณต้องการระบุให้ชัดเจนขึ้นในกล่องโต้ตอบตัวเลือก ดูข้อมูลเพิ่มเติมได้ที่อนุญาตให้แอปอื่นๆ เริ่มกิจกรรมของคุณ

สิทธิ์

แอป Android ต้องขอสิทธิ์ในการเข้าถึงข้อมูลที่ละเอียดอ่อนของผู้ใช้ เช่น รายชื่อติดต่อและ SMS หรือฟีเจอร์บางอย่างของระบบ เช่น กล้องและการเข้าถึงอินเทอร์เน็ต สิทธิ์แต่ละรายการจะระบุด้วยป้ายกำกับที่ไม่ซ้ำกัน ตัวอย่างเช่น แอปที่ต้องส่งข้อความ SMS ต้องมีบรรทัดต่อไปนี้ในไฟล์ Manifest

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

ตั้งแต่ Android 6.0 (API ระดับ 23) เป็นต้นไป ผู้ใช้จะอนุมัติหรือปฏิเสธสิทธิ์บางอย่างของแอปขณะที่รันไทม์ได้ แต่ไม่ว่าแอปของคุณจะรองรับ Android เวอร์ชันใด คุณต้องประกาศคําขอสิทธิ์ทั้งหมดด้วยองค์ประกอบ <uses-permission> ในไฟล์ Manifest หากได้รับสิทธิ์ แอปจะใช้ฟีเจอร์ที่ได้รับการปกป้องได้ หากไม่ อุปกรณ์จะพยายามเข้าถึงฟีเจอร์เหล่านั้นไม่สำเร็จ

นอกจากนี้ แอปยังปกป้องคอมโพเนนต์ของตัวเองด้วยสิทธิ์ได้ด้วย โดยจะใช้สิทธิ์ใดก็ได้ที่ Android กำหนดไว้ตามที่แสดงในandroid.Manifest.permission หรือสิทธิ์ที่ประกาศไว้ในแอปอื่น นอกจากนี้ แอปของคุณยังกำหนดสิทธิ์ของตนเองได้ด้วย ประกาศสิทธิ์ใหม่ด้วยองค์ประกอบ <permission>

ดูข้อมูลเพิ่มเติมได้ที่สิทธิ์ใน Android

ความเข้ากันได้ของอุปกรณ์

นอกจากนี้ ไฟล์ Manifest ยังเป็นที่ที่คุณประกาศประเภทฮาร์ดแวร์หรือฟีเจอร์ซอฟต์แวร์ที่แอปของคุณต้องใช้ และโดยขยายความแล้ว ยังเป็นที่ประกาศประเภทอุปกรณ์ที่แอปของคุณเข้ากันได้ด้วย Google Play Store ไม่อนุญาตให้ผู้ใช้ติดตั้งแอปของคุณในอุปกรณ์ที่ไม่มีฟีเจอร์หรือเวอร์ชันระบบที่แอปของคุณต้องใช้

ไฟล์ Manifest มีแท็กหลายแท็กที่กำหนดว่าแอปของคุณเข้ากันได้กับอุปกรณ์ใดบ้าง ตัวอย่างที่พบบ่อยมีดังนี้

<uses-feature>

องค์ประกอบ <uses-feature> ช่วยให้คุณประกาศฟีเจอร์ฮาร์ดแวร์และซอฟต์แวร์ที่แอปต้องการได้ ตัวอย่างเช่น หากแอปของคุณไม่สามารถทํางานตามฟังก์ชันพื้นฐานในอุปกรณ์ที่ไม่มีเซ็นเซอร์เข็มทิศ คุณสามารถประกาศเซ็นเซอร์เข็มทิศเป็น "ต้องระบุ" โดยใช้แท็กไฟล์ Manifest ต่อไปนี้

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

หมายเหตุ: หากต้องการให้แอปพร้อมให้บริการใน Chromebook คุณควรพิจารณาข้อจำกัดที่สำคัญบางอย่างของฮาร์ดแวร์และฟีเจอร์ซอฟต์แวร์ ดูข้อมูลเพิ่มเติมได้ที่ความเข้ากันได้ของไฟล์ Manifest ของแอปสำหรับ Chromebook

<uses-sdk>

แพลตฟอร์มแต่ละเวอร์ชันที่อัปเดตใหม่มักจะเพิ่ม API ใหม่ที่ไม่มีในเวอร์ชันก่อนหน้า หากต้องการระบุเวอร์ชันขั้นต่ำที่แอปของคุณใช้งานร่วมกันได้ ไฟล์ Manifest ต้องมีแท็ก <uses-sdk> และแอตทริบิวต์ minSdkVersion

อย่างไรก็ตาม โปรดทราบว่าพร็อพเพอร์ตี้ที่เกี่ยวข้องในไฟล์ build.gradle จะลบล้างแอตทริบิวต์ในองค์ประกอบ <uses-sdk> ดังนั้น หากคุณใช้ 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 โดยทั่วไป

องค์ประกอบ

ต้องมีองค์ประกอบ <manifest> และ <application>เท่านั้น โดยแต่ละรายการต้องปรากฏเพียงครั้งเดียว องค์ประกอบอื่นๆ ส่วนใหญ่อาจเกิดขึ้นตั้งแต่ 0 ครั้งขึ้นไป อย่างไรก็ตาม ต้องมีองค์ประกอบบางอย่างเพื่อให้ไฟล์ Manifest มีประโยชน์

ค่าทั้งหมดจะตั้งค่าผ่านแอตทริบิวต์ ไม่ใช่เป็นข้อมูลอักขระภายในองค์ประกอบ

โดยทั่วไปแล้ว องค์ประกอบในระดับเดียวกันจะไม่เรียงลำดับ เช่น องค์ประกอบ <activity>, <provider> และ <service> สามารถวางในลำดับใดก็ได้ ข้อยกเว้นสำคัญ 2 ข้อของกฎนี้ ได้แก่

• องค์ประกอบ <activity-alias> ต้องตามหลัง <activity> ที่ใช้เป็นอีเมลแทน
• องค์ประกอบ <application> ต้องเป็นองค์ประกอบสุดท้ายภายในองค์ประกอบ <manifest>

แอตทริบิวต์

ในทางเทคนิคแล้ว แอตทริบิวต์ทั้งหมดเป็นค่าที่ไม่บังคับ อย่างไรก็ตาม คุณต้องระบุแอตทริบิวต์หลายรายการเพื่อให้องค์ประกอบทำงานได้ตามวัตถุประสงค์ สําหรับแอตทริบิวต์ที่ไม่บังคับอย่างแท้จริง เอกสารอ้างอิงจะระบุค่าเริ่มต้น

ชื่อแอตทริบิวต์ทั้งหมดจะขึ้นต้นด้วยคำนำหน้า android: ยกเว้นแอตทริบิวต์บางรายการขององค์ประกอบรูท <manifest> เช่น android:alwaysRetainTaskState เนื่องจากคำนำหน้านี้ใช้ได้กับทุกที่ เอกสารประกอบจึงมักจะไม่ใส่คำนำหน้านี้เมื่ออ้างอิงถึงแอตทริบิวต์ตามชื่อ

มีหลายค่า

หากระบุค่าได้มากกว่า 1 ค่า องค์ประกอบจะซ้ำกันเกือบทุกครั้ง แทนที่จะแสดงค่าหลายค่าภายในองค์ประกอบเดียว ตัวอย่างเช่น ตัวกรอง Intent สามารถแสดงการดำเนินการหลายรายการได้ ดังนี้

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

ค่าทรัพยากร

แอตทริบิวต์บางรายการมีค่าที่แสดงต่อผู้ใช้ เช่น ชื่อกิจกรรมหรือไอคอนแอป ค่าสำหรับแอตทริบิวต์เหล่านี้อาจแตกต่างกันไปตามภาษาของผู้ใช้หรือการกําหนดค่าอุปกรณ์อื่นๆ (เช่น เพื่อระบุขนาดไอคอนที่แตกต่างกันตามความหนาแน่นของพิกเซลของอุปกรณ์) ดังนั้นจึงควรตั้งค่าจากทรัพยากรหรือธีมแทนการเขียนโค้ดลงในไฟล์ Manifest จากนั้นค่าจริงอาจเปลี่ยนแปลงตามแหล่งข้อมูลทางเลือกที่คุณระบุไว้สําหรับการกําหนดค่าอุปกรณ์ที่แตกต่างกัน

ทรัพยากรจะแสดงเป็นค่าในรูปแบบต่อไปนี้

"@[package:]type/name"

คุณละเว้นชื่อ package ได้หากแอปของคุณให้ทรัพยากร (รวมถึงในกรณีที่ทรัพยากรมาจาก Dependency ของไลบรารี เนื่องจากทรัพยากรของไลบรารีจะผสานรวมกับของคุณ) ชื่อแพ็กเกจอื่นๆ ที่ถูกต้องมีเพียง android เท่านั้น ในกรณีที่คุณต้องการใช้ทรัพยากรจากเฟรมเวิร์ก Android

type คือประเภททรัพยากร เช่น string หรือ drawable และ name คือชื่อที่ระบุทรัพยากรที่เฉพาะเจาะจง มีตัวอย่างดังต่อไปนี้

<activity android:icon="@drawable/smallPic" ... >

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีเพิ่มทรัพยากรลงในโปรเจ็กต์ได้ที่ภาพรวมทรัพยากรแอป

หากต้องการใช้ค่าที่กําหนดไว้ในธีมแทน อักขระแรกต้องแทนที่จะเป็น @?

"?[package:]type/name"

ค่าสตริง

ในกรณีที่ค่าแอตทริบิวต์เป็นสตริง ให้ใช้เครื่องหมายแบ็กสแลชคู่ (\\) เพื่อหลีกอักขระ เช่น \\n สำหรับบรรทัดใหม่ หรือ \\uxxxx สำหรับอักขระ Unicode

การอ้างอิงองค์ประกอบไฟล์ Manifest

ตารางต่อไปนี้แสดงลิงก์ไปยังเอกสารอ้างอิงสำหรับองค์ประกอบที่ถูกต้องทั้งหมดในไฟล์ AndroidManifest.xml

ข้อจำกัด

แท็กต่อไปนี้มีการจํากัดจํานวนครั้งที่ปรากฏในไฟล์ Manifest

แอตทริบิวต์ต่อไปนี้มีขีดจำกัดความยาวสูงสุด

ตัวอย่างไฟล์ Manifest

XML ด้านล่างเป็นตัวอย่าง AndroidManifest.xml ง่ายๆ ที่ประกาศกิจกรรม 2 รายการสําหรับแอป

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