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

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

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

• องค์ประกอบของแอป รวมถึงกิจกรรม บริการ Broadcast Receiver และผู้ให้บริการเนื้อหา คอมโพเนนต์แต่ละรายการต้องกำหนดพร็อพเพอร์ตี้พื้นฐาน เช่น ชื่อคลาส 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 ในไฟล์ 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 {
    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>