應用程式資訊清單總覽

在專案來源集的根目錄中，每個應用程式專案都必須設有確切名稱為 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 屬性。

不過請注意，<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> 和 <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>