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

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

สำหรับข้อมูลเพิ่มเติม โปรดดูเอกสาร Intent และตัวกรอง Intent

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

องค์ประกอบไฟล์ 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

Elements

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

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

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

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

แอตทริบิวต์

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

ยกเว้นแอตทริบิวต์บางรายการของรูท <manifest> ชื่อแอตทริบิวต์ทั้งหมดจะขึ้นต้นด้วย android: นำหน้า เช่น 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>