ภาพรวมไฟล์ 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 เป็นจุด ระบบจะนำเนมสเปซของแอปจากไฟล์ 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 คือข้อความที่กำหนดโดย Intentออบเจ็กต์ที่อธิบาย การดำเนินการที่จะทำ รวมถึงข้อมูลที่จะดำเนินการ หมวดหมู่ของ คอมโพเนนต์ที่คาดว่าจะดำเนินการ และคำสั่งอื่นๆ

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

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

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

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

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

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

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

ค่าสตริง

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