應用程式資訊清單總覽

每個應用程式專案都必須在專案來源集的根目錄中設有確切名稱為 AndroidManifest.xml 的檔案。資訊清單檔案會將您應用程式的基本資訊提供給 Android 建構工具、Android 作業系統和 Google Play。

此外，資訊清單檔案也必須宣告以下項目：

• 應用程式元件，包括所有活動、服務、廣播接收器和內容供應器。每個元件都必須定義基本屬性，例如 Kotlin 或 Java 類別的名稱。資訊清單檔案還能宣告可描述元件啟動方式的意圖篩選器，以及各種功能，例如可處理哪些裝置設定。如要進一步瞭解應用程式元件，請參閱下一節。
• 應用程式存取系統或其他應用程式受保護部分所需的權限。資訊清單檔案也可宣告其他應用程式所需的權限，藉此存取該應用程式的內容。如要進一步瞭解權限，請參閱下一節。
• 應用程式所需的硬體和軟體功能，這會影響可從 Google Play 安裝應用程式的裝置。如要進一步瞭解裝置相容性，請參閱下一節。

如果是使用 Android Studio 建構應用程式，系統會自動建立資訊清單檔案，並在應用程式建構期間加入大部分的重要資訊清單元素，尤其是使用程式碼範本進行建構時。

檔案功能

以下各節說明應用程式的幾項重要特性如何反映在資訊清單檔案中。

應用程式元件

對於應用程式中建立的每個應用程式元件，都請在資訊清單檔案中宣告相對應的 XML 元素：

• 每個 Activity 子類別的 <activity>
• 每個 Service 子類別的 <service>
• 每個 BroadcastReceiver 子類別的 <receiver>
• 每個 ContentProvider 子類別的 <provider>

如果您將任何這些元件分入子類別，卻未在資訊清單檔案中宣告，系統就無法啟動該元件。

請使用完整套件指定名稱，透過 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-filter> 元素定義)，每個篩選器會描述該元件的不同功能。

詳情請參閱意圖和意圖篩選器文件。

圖示和標籤

許多資訊清單元素分別有 icon 和 label 屬性，可分別顯示對應的小圖示和文字標籤，方便使用者查看對應的應用程式元件。

在任何情況下，父項元素中設定的圖示和標籤都會成為所有子項元素的預設 icon 和 label 值。舉例來說，在 <application> 元素中設定的圖示和標籤，就是應用程式元件 (比如所有活動) 的預設圖示和標籤。

每當元件是顯示為執行意圖的選項，使用者就會看到元件 <intent-filter> 中設定的圖示和標籤。根據預設，這個圖示會繼承父項元件的宣告圖示，即 <activity> 或 <application> 元素。

如果您希望在選擇器對話方塊中更精準指明意圖篩選器提供的專屬動作，建議您變更意圖篩選器的圖示。詳情請參閱「允許其他應用程式啟動您的活動」。

權限

Android 應用程式必須要求權限，才能存取聯絡人、簡訊等敏感的使用者資料，或相機/網際網路存取權等特定系統功能。每個權限都是採用不重複的識別標籤。舉例來說，如果應用程式需要傳送簡訊，則資訊清單必須包含下列這一行：

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

從 Android 6.0 (API 級別 23) 開始，使用者可以在執行階段核准或拒絕部分應用程式權限。無論應用程式支援的 Android 版本為何，都必須使用資訊清單中的 <uses-permission> 元素宣告所有權限要求。若獲得使用者授權，應用程式就能使用受保護的功能。否則無法順利存取這些功能。

應用程式還可透過權限保護本身的元件可使用 Android 定義的任何權限，如 android.Manifest.permission，或是在其他應用程式中宣告的權限。應用程式也可以定義自己的權限。系統會使用 <permission> 元素宣告新權限。

詳情請參閱「Android 中的權限」。

裝置相容性

資訊清單檔案也可以宣告應用程式所需的硬體或軟體功能類型，以及應用程式因此可與哪些類型的裝置相容。Google Play 商店只允許使用者在提供應用程式所需功能或系統版本的裝置上安裝應用程式。

如要定義與應用程式相容的裝置，可以使用數種資訊清單標記。以下是一些最常見的標記。

<uses-feature>

<uses-feature> 元素可用來宣告應用程式需要的硬體和軟體功能。舉例來說，如果應用程式無法在沒有指南針感應器的裝置上執行基本功能，您可以使用下列資訊清單標記來宣告指南針感應器：

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

注意：如果想在 Chromebook 上提供應用程式，應將一些重要的硬體和軟體功能限制納入考量。詳情請參閱「Chromebook 的應用程式資訊清單相容性」。

<uses-sdk>

每個連續平台版本經常都會新增前一個版本不支援的 API。如要指出與應用程式相容的最低版本，資訊清單必須包含 <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> 和 <application> 元素。兩者均只會出現一次。大多數的其他元素可能出現零次或多次。不過，您必須提供部分元素，才能讓資訊清單檔案更加實用。

所有值都是透過屬性設定，不是透過元素中的半形字元資料。

一般來說，相同層級的元素不會排序。舉例來說，<activity>、<provider> 和 <service> 元素可按任意順序排列。這項規則有兩個重要例外狀況：

• <activity-alias> 元素必須符合作為別名的 <activity>。
• <application> 元素必須是 <manifest> 元素中的最後一個元素。

屬性

技術上來說，所有屬性皆為選填。不過，您必須指定許多屬性，元素才能達到目的。如果是真正的選用屬性，參考說明文件會指出預設值。

除了根 <manifest> 元素的某些屬性以外，所有屬性名稱的開頭都是前置字串 android:，例如 android:alwaysRetainTaskState。由於前置字串是通用的，說明文件一般會在提及屬性名稱時省略前置字串。

多個值

如果可以指定多個值，系統會一律重複顯示元素，而不是在單一元素中列出多個值。舉例來說，意圖篩選器可以列出數個動作：

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

資源值

有些屬性會向使用者顯示值，例如活動標題或應用程式圖示。根據使用者的語言或其他裝置設定 (例如依裝置像素密度提供不同的圖示大小)，這些屬性的值可能會有所不同，因此這些值應從資源或主題設定，而不是以硬式編碼的方式寫入資訊清單檔案。實際值可能會根據您為不同裝置設定提供的替代資源而變動。

資源會以下列格式表示：

"@[package:]type/name"

如果資源是由應用程式提供，則可以省略 package 名稱。如果已合併程式庫資源，那麼由程式庫依附元件提供的資源也可以省略名稱。想使用 Android 架構中的資源時，其他有效的套件名稱為 android。

type 是資源類型，例如 string 或 drawable，而 name 是用來識別特定資源的名稱。範例如下：

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

如要進一步瞭解如何新增資源至專案，請參閱「應用程式資源總覽」。

如要取代在主題中定義的值，第一個半形字元必須是 ?，而不是 @：

"?[package:]type/name"

字串值

如果屬性值是字串，請使用雙反斜線 (\\) 逸出半形字元，例如使用 \\n 做為換行符號，或使用 \\uxxxx 代表萬國碼 (Unicode) 半形字元。

資訊清單元素參考資料

下表提供 AndroidManifest.xml 檔案中所有有效元素的參考文件連結。

資訊清單檔案範例

下方的 XML 是簡單的 AndroidManifest.xml 範例，可宣告應用程式的兩個活動。

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