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

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

ไฟล์ Manifest ต้องประกาศสิ่งต่อไปนี้ รวมถึงสิ่งอื่นๆ อีกมากมาย

• คอมโพเนนต์ของแอป ซึ่งรวมถึงกิจกรรม บริการ Broadcast Receiver และ Content Provider ทั้งหมด แต่ละคอมโพเนนต์ต้องกำหนดพร็อพเพอร์ตี้พื้นฐาน เช่น ชื่อคลาส 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

กิจกรรม บริการ และ Broadcast Receiver ของแอปจะเปิดใช้งานโดย 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

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

android {
    defaultConfig {
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdkVersion 23

        // Specifies the API level used to test the app.
        targetSdkVersion 36
        ...
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(23)

        // Specifies the API level used to test the app.
        targetSdkVersion(36)
        ...
    }
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์ build.gradle ได้ที่วิธีกำหนดค่าบิลด์

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีประกาศการรองรับอุปกรณ์ต่างๆ ของแอปได้ที่ภาพรวมความเข้ากันได้ของอุปกรณ์

รูปแบบไฟล์

ส่วนนี้จะอธิบายแบบแผนและกฎที่ใช้โดยทั่วไปกับองค์ประกอบและแอตทริบิวต์ทั้งหมดในไฟล์ Manifest

องค์ประกอบ

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

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

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

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

แอตทริบิวต์

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

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

มีหลายค่า

หากระบุค่าได้มากกว่า 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"

ค่าสตริง

ในกรณีที่ค่าแอตทริบิวต์เป็นสตริง ให้ใช้แบ็กสแลช 2 ตัว (\\) เพื่อหลีกอักขระ เช่น \\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>