應用程式資訊清單總覽

每個應用程式專案都必須在專案來源集的根目錄中有一個 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> 元素宣告新權限。

詳情請參閱權限總覽一文。

裝置相容性

也可以利用資訊清單檔案來宣告應用程式需要哪些類型的硬體或軟體功能，因此應用程式要與哪些類型的裝置相容。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 代表萬國碼半形字元。

資訊清單元素參考資料

下表提供 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 upon 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>