應用程式資訊清單總覽

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

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

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

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

檔案功能

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

應用程式元件

對於在應用程式中建立的每個應用程式元件,您都需在資訊清單檔案中宣告相對應的 XML 元素:

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

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

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

圖示和標籤

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

在任何情況下,只要是父項元素中設定的圖示和標籤,都會成為所有子項元素的預設 iconlabel 值。舉例來說,在 <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,請改為指定 minSdkVersiontargetSdkVersion 的值:

Groovy

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

Kotlin

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 是資源類型,例如 stringdrawable,而 name 是用來識別特定資源的名稱。範例如下:

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

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

如要改為套用在主題中定義的值,第一個半形字元必須是 ?,而不是 @

"?[package:]type/name"

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

資訊清單元素參考資料

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

<action> 將動作新增至意圖篩選器。
<activity> 宣告活動元件。
<activity-alias> 宣告活動的別名。
<application> 宣告應用程式。
<category> 在意圖篩選器中加入類別名稱。
<compatible-screens> 指定與應用程式相容的各個螢幕設定。
<data> 將資料規格新增至意圖篩選器。
<grant-uri-permission> 指定父項內容供應器有權存取的應用程式資料子集。
<instrumentation> 宣告 Instrumentation 類別,方便監控應用程式與系統互動的情況。
<intent-filter> 指定活動、服務或廣播接收器可回應的意圖類型。
<manifest> AndroidManifest.xml 檔案的根元素。
<meta-data> 其他任意資料的項目名稱/值組合,可提供到父項元件。
<path-permission> 定義內容供應者中特定資料子集的路徑和必要權限。
<permission> 宣告安全性權限,以限制此應用程式或其他應用程式特定元件或功能的存取權。
<permission-group> 宣告相關權限之邏輯群組的名稱。
<permission-tree> 宣告權限樹狀結構的基礎名稱。
<provider> 宣告內容供應器元件。
<queries> 宣告應用程式要存取的其他應用程式組合。詳情請參閱套件瀏覽權限篩選條件指南。
<receiver> 宣告廣播接收器元件。
<service> 宣告服務元件。
<supports-gl-texture> 宣告應用程式支援的單一 GL 材質壓縮格式。
<supports-screens> 宣告應用程式支援的螢幕大小,並為大於應用程式支援的畫面啟用螢幕相容模式。
<uses-configuration> 指出應用程式所需的特定輸入特色。
<uses-feature> 宣告應用程式使用的一項硬體或軟體功能。
<uses-library> 指定應用程式必須建立連結的共用資料庫。
<uses-native-library> 指定應用程式必須連結供應商的原生共用資料庫。
<uses-permission> 指定使用者必須授予的系統權限,應用程式才能正常運作。
<uses-permission-sdk-23> 指出應用程式需要定權限,但前提是該應用程式必須安裝在搭載 Android 6.0 (API 級別 23) 及以上版本的裝置上。
<uses-sdk> 您可透過整數形式的 API 級別,表達應用程式與一或多個版本 Android 平台的相容性。

限制

下列標記在資訊清單檔案中的出現次數有限制:

標記名稱 每日使用時間上限
<package> 1000
<meta-data> 1000
<uses-library> 1000

下列屬性有長度上限:

屬性 每日使用時間上限
name 1024
versionName 1024
host 255
mimeType 255

資訊清單檔案範例

下方的 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>