在專案來源集的根目錄中,每個應用程式專案都必須設有確切名稱為 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
的值:
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 是資源類型,例如
string
或drawable
,而 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>