<活動>

語法:
<activity android:allowEmbedded=["true" | "false"]
          android:allowTaskReparenting=["true" | "false"]
          android:alwaysRetainTaskState=["true" | "false"]
          android:autoRemoveFromRecents=["true" | "false"]
          android:banner="drawable resource"
          android:clearTaskOnLaunch=["true" | "false"]
          android:colorMode=[ "hdr" | "wideColorGamut"]
          android:configChanges=["mcc", "mnc", "locale",
                                 "touchscreen", "keyboard", "keyboardHidden",
                                 "navigation", "screenLayout", "fontScale",
                                 "uiMode", "orientation", "density",
                                 "screenSize", "smallestScreenSize"]
          android:directBootAware=["true" | "false"]
          android:documentLaunchMode=["intoExisting" | "always" |
                                  "none" | "never"]
          android:enabled=["true" | "false"]
          android:enabledOnBackInvokedCallback=["true" | "false"]
          android:excludeFromRecents=["true" | "false"]
          android:exported=["true" | "false"]
          android:finishOnTaskLaunch=["true" | "false"]
          android:hardwareAccelerated=["true" | "false"]
          android:icon="drawable resource"
          android:immersive=["true" | "false"]
          android:label="string resource"
          android:launchMode=["standard" | "singleTop" |
                              "singleTask" | "singleInstance" | "singleInstancePerTask"]
          android:lockTaskMode=["normal" | "never" |
                              "if_whitelisted" | "always"]
          android:maxRecents="integer"
          android:maxAspectRatio="float"
          android:multiprocess=["true" | "false"]
          android:name="string"
          android:noHistory=["true" | "false"]  
          android:parentActivityName="string" 
          android:persistableMode=["persistRootOnly" | 
                                   "persistAcrossReboots" | "persistNever"]
          android:permission="string"
          android:process="string"
          android:relinquishTaskIdentity=["true" | "false"]
          android:resizeableActivity=["true" | "false"]
          android:screenOrientation=["unspecified" | "behind" |
                                     "landscape" | "portrait" |
                                     "reverseLandscape" | "reversePortrait" |
                                     "sensorLandscape" | "sensorPortrait" |
                                     "userLandscape" | "userPortrait" |
                                     "sensor" | "fullSensor" | "nosensor" |
                                     "user" | "fullUser" | "locked"]
          android:showForAllUsers=["true" | "false"]
          android:stateNotNeeded=["true" | "false"]
          android:supportsPictureInPicture=["true" | "false"]
          android:taskAffinity="string"
          android:theme="resource or theme"
          android:uiOptions=["none" | "splitActionBarWhenNarrow"]
          android:windowSoftInputMode=["stateUnspecified",
                                       "stateUnchanged", "stateHidden",
                                       "stateAlwaysHidden", "stateVisible",
                                       "stateAlwaysVisible", "adjustUnspecified",
                                       "adjustResize", "adjustPan"] >   
    ...
</activity>
包含於:
<application>
可包含:
<intent-filter>
<meta-data>
<layout>
說明:
宣告一個活動 (一個 Activity 子類別),實作應用程式視覺化使用者介面的一部分。所有活動都必須以資訊清單檔案中的 <activity> 元素呈現。系統不會偵測到任何未在此宣告的活動,因此也不會執行這類活動。
屬性:
android:allowEmbedded
表示該活動可能會做為另一個活動的嵌入式子項來啟動,特別是當子項位於容器內時,例如另一個活動擁有的 Display。舉例來說,用於 Wear 自訂通知的活動宣告這項資訊,讓 Wear 可以在位於另一程序內的內容串流中顯示活動。

此屬性的預設值為 false

android:allowTaskReparenting
可指定下次該活動移至前景時,活動可否從啟動活動的任務移至具相依性的任務。如果可以移動,則為 "true";如果活動仍位於啟動該活動的工作中,則為 "false"

如未設定此屬性,系統會將 <application> 元素相應 allowTaskReparenting 屬性設定的值套用至活動。預設值為 "false"

一般而言,在活動開始後,活動才會與啟動活動的任務建立關聯,而且在整個生命週期中都會保留在該任務中。當活動的現有任務不再顯示時,您可以使用此屬性強制將活動的父項重新改為與其具有相依性的任務。這個屬性常見的用途為,促使應用程式的活動移至與該應用程式相關聯的主要任務中。

舉例來說,如果電子郵件內含網頁連結,點選該連結就會帶出可以顯示該網頁的活動。該活動是由瀏覽器應用程式定義,卻做為電子郵件任務的一環來啟動。如果將該活動的父項更改為瀏覽器任務,活動就會在瀏覽器下次轉至前景時顯示,而在電子郵件任務再次轉至前景時消失。

活動的相依性是由 taskAffinity 屬性定義。讀取任務根活動的相依性,即可判定任務的相依性。因此,根據定義,根活動一律會位於具有同一相依性的任務中。由於具有 "singleTask""singleInstance" 啟動模式的活動只能存在於任務的根層級,更改父項作業只能在 "standard""singleTop" 模式下進行(另請參閱 launchMode 屬性)。

android:alwaysRetainTaskState
活動所處的任務狀態是否會一直由系統維護。"true" 表示會,"false" 表示系統可以在特定情況下,將任務重設為初始狀態。預設值為 "false"。這項屬性僅適用於任務的根活動,其他所有活動都會忽略此屬性。

一般而言,當使用者在主畫面上重新選取任務時,系統會在特定情況下清除該任務 (也就是從根活動上方的堆疊中移除所有活動)。通常,如果使用者在一段時間內 (例如 30 分鐘) 未造訪任務,系統就會執行這項作業。

但是,如果這項屬性為 "true",則無論使用者如何前往任務,他們一律會返回任務上次的狀態。網路瀏覽器具有許多使用者想要保留的狀態 (例如多個開啟的分頁),因此這項功能在這類應用程式中非常實用。

android:autoRemoveFromRecents
指定含有此屬性的活動所啟動的任務,是否要保留在「最近使用」畫面,直到任務中的最後一個活動完成為止。如果為 true,則任務會自動從「最近使用」畫面中移除。這會覆寫呼叫端使用的 FLAG_ACTIVITY_RETAIN_IN_RECENTS。這個值必須是布林值,可以是 "true""false"
android:banner
這是一種可繪製資源,用於為關聯項目提供延伸圖片橫幅。與 <activity> 標記搭配使用,可提供特定活動的預設橫幅,而與 <application> 標記搭配使用,則可為所有應用程式活動提供橫幅。

系統會使用橫幅來代表 Android TV 主畫面上的應用程式。橫幅只會顯示在主畫面上,因此只有在應用程式含有處理 CATEGORY_LEANBACK_LAUNCHER 意圖的活動時,才會指定橫幅。

這項屬性會設為包含圖片的可繪製資源參照,例如 "@drawable/banner"。此屬性沒有預設橫幅。

詳情請參閱「開始使用電視應用程式」中的「 提供主畫面橫幅」一節。

android:clearTaskOnLaunch
可指定從主畫面重新啟動任務時,是否要從任務中移除根活動之外的所有活動。 "true" 表示一律要移除任務的活動,直到剩下根活動為止,"false" 則表示不要移除。預設值為 "false"。這項屬性僅適用於會啟動新任務的活動 (根活動),任務中的所有其他活動均會忽略此屬性。

若值為 "true",每次使用者啟動任務時,系統都會將他們導向至任務的根活動;不論使用者最後在任務中執行什麼操作,或是否利用「返回」或「主畫面」按鈕退出任務,結果都會一樣。當值為 "false" 時,可以在某些情況下清除任務的所有活動,但並非一律如此。詳情請參閱 alwaysRetainTaskState 屬性。

假設使用者在主畫面上啟動活動 P,然後從該處前往活動 Q。接著,使用者按下主畫面按鈕,再返回活動 P。使用者通常會看到活動 Q,因為這是他們最後在 P 任務中執行的活動。不過,如果 P 將這個旗標設為 "true",則當使用者從主畫面啟動活動 P 時,系統會移除 P 上方的所有活動 (在本例中為 Q)。因此,使用者返回任務時只會看到 P。

如果此屬性和 allowTaskReparenting 皆為 "true",則任何可更改父項的活動均會移至具有相依性的任務,然後捨棄剩餘的活動。

如未設定 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED,系統會忽略這個屬性。

android:colorMode

指定活動的色彩模式,可指定為 hdrwideColorGamut

如果設為 hdr,則若裝置支援,要求會在高動態範圍中顯示活動。

如果設為 wideColorGamut,則要求會在相容裝置上以廣色域模式顯示活動。在廣色域模式下,視窗可在 SRGB 以外的區域轉譯,顯示更加鮮豔的色彩。如果裝置不支援廣色域顯示,這個屬性就不會有任何作用。如要進一步瞭解如何在廣色模式下顯示內容,請參閱「使用廣色內容增強圖像效果」一文。

android:configChanges
列出活動本身處理的設定變更。根據預設,在執行階段發生設定變更時,系統會關閉並重新啟動活動,如果用這項屬性宣告設定,則會造成活動無法重新啟動,相反地,活動會保持運作,而且系統會呼叫其 onConfigurationChanged() 方法。

注意:請只在特殊情況下才使用這個屬性,以便提高應用程式的效能和回應速度。詳情請參閱「處理設定變更」一文。

下列字串是這項屬性的有效值。多個值之間以 | 分隔,例如 "locale|navigation|orientation"

說明
"density" 變更顯示密度,例如使用者指定不同的螢幕縮放比例,或是現已啟用其他螢幕。

已在 API 級別 24 中新增

"fontScale" 變更字型縮放係數,例如使用者選擇新的全域字型大小。
"keyboard" 變更鍵盤類型,例如使用者連接外接鍵盤。
"keyboardHidden" 變更鍵盤的無障礙功能,例如在使用者採用了硬體鍵盤。
"layoutDirection" 變更版面配置方向,例如從由左到右 (LTR) 變更為由右到左 (RTL)。

已新增至 API 等級 17

"locale" 變更語言代碼,例如使用者選取新的文字顯示語言。
"mcc" 變更 IMSI 行動裝置國家/地區代碼 (MCC),這發生在系統偵測到會更新 MCC 的 SIM 卡時。
"mnc" 變更 IMSI 行動網路代碼 (MNC) 時,當系統偵測到可更新 MNC 的 SIM 卡時,就會發生變更。
"navigation" 變更導覽類型的 TA (軌跡球或 D-Pad)。通常不會發生這種情形。
"orientation"

變更螢幕方向,例如使用者旋轉裝置。

注意:如果應用程式指定的是 Android 3.2 (API 級別 13) 以上版本,也請一併宣告 "screenLayout""screenSize" 設定,因為當裝置在直向和橫向模式間切換時,螢幕版面配置和螢幕大小可能會隨之變更。

"screenLayout" 變更螢幕版面配置,例如使用者啟動其他螢幕。
"screenSize" 變更目前可用的螢幕大小。

這代表目前可用尺寸相對於當前顯示比例的更改幅度,所以當使用者在橫向和直向之間切換時,這個值就會變動。

已新增至 API 等級 13

"smallestScreenSize" 變更實體螢幕大小。

這代表了尺寸的變化,與方向無關,所以只有在實際的實體螢幕尺寸發生變化時才會改變,例如切換到外部顯示器。這項設定的變更會與 smallestWidth 設定的變更相對應。

已新增至 API 等級 13

"touchscreen" 變更觸控螢幕。通常不會發生這種情形。
"uiMode" 變更使用者介面模式,例如使用者將裝置放到桌面或車用座架上,或更改了夜間模式。如要進一步瞭解不同的 UI 模式,請參閱 UiModeManager

已在 API 級別 8 中新增。

所有這些設定變更都會影響應用程式看到的資源值。因此,在呼叫 onConfigurationChanged() 時,通常需要再次擷取所有資源 (包括檢視區塊版面配置和可繪項目),才能正確處理變更。

注意:如要處理與多視窗模式相關的設定變更,請同時使用 "screenLayout""smallestScreenSize"。Android 7.0 (API 級別 24) 以上版本支援多視窗模式。

android:directBootAware

表示活動是否具有「直接啟動感知特性」,也就是能否在使用者解鎖裝置前執行。

注意:直接啟動期間,應用程式中的活動只能存取儲存在「受裝置保護」儲存空間中的資料。

預設值為 "false"

android:documentLaunchMode
指定每次啟動任務時,如何在任務中新增活動的例項。藉由這個屬性,使用者可讓同一應用程式的多個文件顯示在「最近使用」畫面上。

這個屬性有四個值,當使用者透過應用程式開啟文件時,會產生以下效果:

說明
"intoExisting" 系統會搜索一個任務,其基本意圖 ComponentName 和資料 URI 與啟動意圖相匹配。如果找到這類任務,系統會將其清除,並透過根活動重新啟動,根活動則會收到對 onNewIntent(android.content.Intent) 的呼叫。如果系統沒有找到這樣的任務,系統會建立一個新的任務。
"always" 即使文件已開啟,活動仍會為文件建立新的任務。這與同時設定 FLAG_ACTIVITY_NEW_DOCUMENTFLAG_ACTIVITY_MULTIPLE_TASK 旗標的效果相同。
"none" 該活動不會為活動建立新任務。這是預設值,只有在已設定 FLAG_ACTIVITY_NEW_TASK 時才會建立新任務。「Recents」畫面會按照預設方式處理活動,也就是為應用程式顯示單一任務,並從使用者上次叫用的任意活動繼續執行。
"never" 即使 Intent 包含 FLAG_ACTIVITY_NEW_DOCUMENT,系統也不會在新文件中啟動這項活動。這項設定會覆寫 FLAG_ACTIVITY_NEW_DOCUMENTFLAG_ACTIVITY_MULTIPLE_TASK 旗標的行為 (如果活動中已設定這類標記),且「最近使用」畫面會顯示應用程式的單一工作,從使用者上次叫用的活動繼續播放內容。

注意:如果值不是 "none""never",活動必須以 launchMode="standard" 定義。如未指定這項屬性,則會使用 documentLaunchMode="none"

android:enabled
表示系統可否建立活動的例項。"true" 表示可以,"false" 表示不可以。預設值為 "true"

<application> 元素提供專屬的 enabled 屬性,適用於包括活動在內的所有應用程式元件。<application><activity> 屬性都必須為 "true",因為兩者都採用這個預設值時,系統就能建立活動的例項。只要其中一個是 "false",就無法建立例項。

android:enableOnBackInvokedCallback
這個旗標可讓你選擇在活動層級啟用預測系統動畫。這項行為可更輕鬆管理將大型多活動應用程式遷移至預測返回手勢的過程。

設定 android:enableOnBackInvokedCallback=false 會依據標記設定位置,在活動層級或應用程式層級關閉預測返回動畫,並指示系統忽略對 OnBackInvokedCallback 平台 API 的呼叫。

android:excludeFromRecents
表示 「最近使用」畫面是否要排除由此活動啟動的任務。也就是說,如果這個活動是新任務的根活動,這項屬性就能決定任務是否要顯示在最近使用的應用程式清單中。如果要從清單中「排除」該任務,請設為 "true";如果要「納入」清單,請設為 "false"。預設值為 "false"

android:exported
設定是否能由其他應用程式的元件啟動此活動:

  • 如果是 "true",表示任何應用程式皆可存取該活動,且可使用確切的類別名稱啟動活動。
  • 如果是 "false",表示只有同一個應用程式的元件、具有相同使用者 ID 的應用程式,或具備特殊權限的系統元件,才能啟動該活動。如果沒有意圖篩選器,則此為預設值。

如果應用程式中的活動包含意圖篩選器,請將這項元素設為 "true",讓其他應用程式啟動。例如,活動是應用程式的主要活動,且包含 category android.intent.category.LAUNCHER

如果此元素設為 "false",且應用程式嘗試啟動活動,系統會擲回 ActivityNotFoundException

這項屬性並不是限制活動向其他應用程式公開的唯一方式。權限也可以用來限制可叫用活動的外部實體。詳情請參閱 permission 屬性。

android:finishOnTaskLaunch
設定當使用者在主畫面上選擇任務,藉此重新啟動該任務時,是否要關閉其中活動的現有例項 (根活動除外)。"true" 表示要關閉,"false" 表示不要關閉。預設值為 "false"

如果這個屬性和 allowTaskReparenting 都是 "true",則這項屬性優先於其他屬性。系統會忽略該活動相依性。因此不會更改該活動的父項,而會予以刪除。

如未設定 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED,系統會忽略這個屬性。

android:hardwareAccelerated
可指定是否為此活動啟用硬體加速轉譯功能。"true" 表示已啟用,"false" 則為不啟用。預設值為 "false"

在 Android 3.0 以上版本中,應用程式可以使用硬體加速的 OpenGL 轉譯器,提高許多常見 2D 圖形作業的效能。啟用硬體加速轉譯器後,Canvas、Paint、Xfermode、ColorFilter、Shder 和 Camera 中的大多數作業都會加速。

因此,就算應用程式沒有明確使用架構的 OpenGL 程式庫,也能讓動畫更流暢、捲動更順暢,並且改善整體回應靈敏度。由於啟用硬體加速所需的資源增加,應用程式會耗用更多 RAM。

並非所有 OpenGL 2D 運算都會加速。如果您啟用了硬體加速轉譯器,請測試應用程式是否可以在沒有發生錯誤的情況下使用轉譯器。

android:icon
代表活動的圖示。當需要在螢幕上顯示活動時,該圖示會顯示給使用者。舉例來說,啟動工作的活動圖示會顯示在啟動器視窗中。圖示通常會與標籤一起顯示。如需標籤的相關資訊,請參閱 android:label 屬性。

這項屬性會設為包含圖片定義的可繪製資源參照。如未設定,系統會改用針對應用程式整體指定的圖示。詳情請參閱 <application> 元素的 icon 屬性相關說明。

活動的圖示 (無論是在這裡設定,或由 <application> 元素設定) 也是所有活動的意圖篩選器預設圖示。詳情請參閱 <intent-filter> 元素的 icon 屬性相關說明。

android:immersive
設定當前活動的沉浸模式設定。如果是 "true",則 ActivityInfo.flags 成員一律會設定其 FLAG_IMMERSIVE 位元,即使在執行階段使用 setImmersive() 方法變更沉浸模式也一樣。
android:label
使用者可讀取的活動標籤。系統向使用者呈現活動時,會在畫面上顯示標籤。此標籤經常與活動圖示一起顯示。如未設定這項屬性,系統會改用針對應用程式整體設定的標籤。請參閱 <application> 元素的 label 屬性相關說明。

活動的標籤 (無論是在這裡設定,或由 <application> 元素設定) 也是所有活動的意圖篩選器的預設標籤。詳情請參閱 <intent-filter> 元素的 label 屬性相關說明。

這個標籤應設為字串資源的參照,這樣才能像使用者介面中的其他字串一樣進行本地化。不過為了方便起見,您也可以在開發應用程式時將其設為原始字串。

android:launchMode
活動啟動方式的指示。有五種模式可與 Intent 物件中的活動旗標 (FLAG_ACTIVITY_* 常數) 搭配運作,判定在呼叫活動來處理意圖時應執行什麼動作:

"standard"
"singleTop"
"singleTask"
"singleInstance"
"singleInstancePerTask"

預設模式為 "standard"

如下表所示,這些模式分為兩個主要群組,一邊是 "standard""singleTop" 活動,另一邊則是 "singleTask""singleInstance""singleInstancePerTask" 活動。具有 "standard""singleTop" 啟動模式的活動可以多次例項化。

例項可以屬於任何任務,也可以位於活動任務中的任何位置。一般情況下,系統會在呼叫 startActivity() 的任務中啟動這些例項。除非 Intent 物件包含 FLAG_ACTIVITY_NEW_TASK 指示,在此情況下,系統會選擇其他任務。詳情請參閱 taskAffinity 屬性相關說明。

相對地,"singleTask""singleInstance""singleInstancePerTask" 活動的行為不同。"singleInstancePerTask" 一律位於活動任務的根層級。此外,裝置一次只能容納一個 "singleInstance" 活動例項;如果已設定 FLAG_ACTIVITY_MULTIPLE_TASKFLAG_ACTIVITY_NEW_DOCUMENT"singleInstancePerTask 活動則可在不同任務中多次例項化。

啟動模式為 "singleTask" 的活動會結合 "singleInstance""singleInstancePerTask" 的行為:活動可以多次例項化,且可位於相同 taskAffinity 任務中的任何位置。但是,裝置一次只能容納一個任務,用來在活動任務的根層級找出 "singleTask" 活動。

"standard""singleTop" 模式在一個方面有區別。每當 "standard" 活動有一個新意圖時,系統就會建立回應這個意圖的新類別例項。每個執行個體都處理一個單一意圖。同樣地,您也可以建立新的 "singleTop" 活動例項來處理新意圖。

然而,如果目標任務的堆疊頂端已經有一個活動例項,則該例項會在 onNewIntent() 呼叫中接收新的意圖。系統不會建立新例項。另一種情況是,現有的 "singleTop" 活動例項在目標任務中,但不在堆疊頂端,或者位於堆疊頂端,但不在目標任務中,這時系統會建立新例項並推送至堆疊上。

同樣地,如果使用者向上導覽至目前堆疊上的活動,行為會由父項活動的啟動模式決定。如果父項活動的啟動模式為 singleTop (或 up 意圖包含 FLAG_ACTIVITY_CLEAR_TOP),系統會將父項移至堆疊頂端,並保留其狀態。

瀏覽意圖是由父項活動的 onNewIntent() 方法接收。如果父項活動的啟動模式為 standard,且 up 意圖不包含 FLAG_ACTIVITY_CLEAR_TOP,系統會將目前活動及其父項從堆疊中彈出,並建立父項活動的新例項來接收導覽意圖。

"singleInstance" 模式與 "singleTask""singleInstancePerTask" 也只在一個方面有區別。啟動模式為 "singleTask""singleInstancePerTask" 的活動可讓其他活動 (必須是 "standard""singleTop" 活動) 加入其任務。

另一方面,"singleInstance" 活動不允許其他活動加入其任務,這必須是任務中的唯一活動。如果該活動啟動另一個活動,後者會分配到其他任務內,如同 FLAG_ACTIVITY_NEW_TASK 在意圖中的情況。

用途 啟動模式 可否有多個例項? 留言
大多數活動的正常啟動 "standard" 預設。系統一律會在目標工作中建立新的活動執行個體,並將意圖轉送到該工作。
"singleTop" 有條件 如果在目標任務的頂端已經存在一個活動的執行個體,系統就會透過呼叫該執行個體的 onNewIntent() 方法將意圖轉送到該執行個體,不會建立該活動的新執行個體。
專門啟動
(不建議一般用途)
"singleTask" 有條件 系統會在新工作的根層級中建立活動,或設有同樣相依性的現有任務中尋找該活動。如果該活動內已有執行個體,且該執行個體位於任務根層級,則系統會透過呼叫該執行個體的 onNewIntent() 方法將意圖轉送到該執行個體,而不會建立新的執行個體。
"singleInstance" "singleTask" 相同,只是系統不會在容納例項的任務中啟動任何其他活動。該活動始終是其任務中唯一的成員。
"singleInstancePerTask" 有條件 活動只能以任務的根活動 (建立該任務的第一個活動) 的形式執行,因此這個活動在任務內只會有一個例項。不過,此活動可在不同任務中多次例項化。

如上表所示,"standard" 為預設模式,適用於大多數類型的活動。"singleTop" 也是用於多種類型的活動,是相當實用的啟動模式。"singleTask""singleInstance""singleInstancePerTask" 等其他模式「不適合」大多數應用程式使用。這類模式產生的互動模式,可能會讓使用者感到陌生,且與大多數其他應用程式大不相同。

無論您選擇哪種啟動模式,請確保在啟動過程中,以及使用「返回」按鈕從其他活動和任務返回時,對活動進行可用性測試。

如要進一步瞭解啟動模式及其與 Intent 旗標的互動方式,請參閱「任務和返回堆疊」一文。

android:lockTaskMode
決定裝置以鎖定任務模式執行時,系統如何顯示這個活動。

Android 能以類似資訊站的方式執行任務,這種沉浸式的做法稱為鎖定任務模式。當系統在鎖定任務模式下執行時,裝置使用者通常無法看到通知、無法存取未列入許可清單的應用程式,也無法返回主畫面 (除非已將 Google Home 應用程式列入許可清單)。

只有經裝置政策控制器 (DPC) 列入許可清單的應用程式,才能在系統處於鎖定任務模式時執行。不過,系統和具有特殊權限的應用程式可以在鎖定任務模式下執行,而不必加入許可清單。

這個值可以是下列任一 R.attr.lockTaskMode 字串值:

說明
"normal" 預設值。這是預設值。系統不會在鎖定任務模式中啟動任務,但您可以藉由呼叫 startLockTask() 讓其處於該模式。
"never"

任務不會在 lockTask 模式下啟動,裝置使用者也無法從「最近使用」畫面固定這些任務。

注意事項:這個模式僅適用於系統和具有權限的應用程式。具有該值的非權限應用程式被視為normal

"if_whitelisted" 如果 DPC 使用 DevicePolicyManager.setLockTaskPackages() 來授權這個套件,代表這種模式與 always 相同,唯一區別是,如果該活動是最後一個經鎖定的任務,就需要呼叫 stopLockTask() 才能完成。如果 DPC 未授權這個套件,則代表這個模式與 normal 相同。
"always"

位於此活動根層級的任務,一律會在鎖定任務模式下啟動。如果系統在這項任務啟動時已處於鎖定任務模式,新的任務會在目前的任務上方啟動。在此模式下啟動的工作可呼叫 finish() 以離開鎖定工作模式。

注意事項:這個模式僅適用於系統和具有權限的應用程式。具有該值的非權限應用程式被視為normal

這項屬性是在 API 級別 23 中導入。

android:maxRecents
「最近使用」畫面中,根層級為此活動的任務數量上限。達到這個項目數量時,系統會從「最近使用」畫面中移除最近最少使用的例項。有效值是介於 1 到 50 之間的整數,在低記憶體裝置上則為 1 到 25 之間。0 為無效值。預設值為 16。
android:maxAspectRatio

該活動支援的最大長寬比。如果應用程式在寬高比的裝置上運行,系統會自動對應用程式進行上下黑邊處理,留下部分未使用的螢幕,以便應用程式能夠以其指定的最大寬高比運行。

將裝置長邊除以短邊所得的商 (以小數形式表示),就是最大顯示比例。舉例來說,如果長寬比上限是 7:3,請將這個屬性的值設為 2.33。

在非穿戴式裝置上,這項屬性的值必須為 1.33 以上。在穿戴式裝置上則必須為 1.0 以上。否則系統會忽略設定值。

注意事項:如果活動將 resizeableActivity 設為 true,系統會忽略這個屬性,因為您的活動支援任何大小。

如要進一步瞭解這項屬性,請參閱「宣告最大顯示比例」。

android:multiprocess
設定能否在啟動活動的元件程序中,啟動活動的例項。"true" 表示可以,"false" 表示不可以。預設值為 "false"

通常,系統會在定義例項的應用程式程序中,啟動活動的新例項,因此該活動的所有例項都會在同一個程序中執行。然而,如果這個旗標設為 "true",活動的例項就能在多個程序中執行,讓系統在任何會用到例項的地方建立例項 (前提是權限允許),但這幾乎毫無必要。

android:name
實作活動的類別名稱,為 Activity 的子類別。屬性值通常是完整的類別名稱,例如 "com.example.project.ExtracurricularActivity"。不過為了精簡起見,如果名稱的第一個字元是半形句號 (例如 ".ExtracurricularActivity"),則會加到 build.gradle 檔案中指定的命名空間後方。

發布應用程式後,除非您已設定 android:exported="false",否則請勿變更這個名稱。這項屬性沒有預設值。必須指定名稱。

android:noHistory
當使用者離開活動且已無法在畫面上看到該活動時,是否要呼叫該活動的 finish() 方法,從活動堆疊中予以移除並結束。"true" 表示要結束活動,"false" 表示不要結束。預設值為 "false"

"true" 值表示該活動不會留下歷史追蹤記錄。系統不會將該活動保留在任務的活動堆疊中,因此使用者無法返回。在這種情況下,如果您透過啟動另一個活動來取得此活動的結果,系統就一律不會呼叫 onActivityResult()

這項屬性是在 API 級別 3 中導入。

android:parentActivityName
活動的邏輯父類的類別。這裡的名稱必須符合相應 <activity> 元素的 android:name 屬性所指定的類別名稱。

當使用者輕觸動作列中的向上按鈕時,系統會讀取這項屬性來決定要啟動哪個活動。系統也能使用這項資訊,利用 TaskStackBuilder 將活動返回堆疊彙整在一起。

若要支援 API 級別 4 到 16,您也可以用一個 <meta-data> 元素來宣告父項活動,該元素須指定 "android.support.PARENT_ACTIVITY" 的值:

<activity
    android:name="com.example.app.ChildActivity"
    android:label="@string/title_child_activity"
    android:parentActivityName="com.example.app.MainActivity" >
    <!-- Parent activity meta-data to support API level 4+ -->
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="com.example.app.MainActivity" />
</activity>

如要進一步瞭解如何宣告父項活動來支援向上導覽機制,請參閱導覽說明。

這項屬性是在 API 級別 16 中導入。

android:persistableMode

定義一個活動的執行個體如何在包含任務的裝置重新啟動時被保留。

如果任務的根活動將這個屬性的值設為 persistRootOnly,系統便只會保留根活動。否則,系統會檢查任務返回堆疊中位置較高的活動,如果其中有將這個屬性值設為 persistAcrossReboots 的活動,也都會保留下來。

如果使用這個屬性,則必須將其值設為下列其中一個值:

說明
persistRootOnly 預設值。 當系統重新啟動時,活動任務被保留下來,但只有根層級活動的啟動意圖被使用。

當應用程式的啟動意圖載入應用程式的根活動時,活動並不會收到 PersistableBundle 物件。因此,請勿利用 onSaveInstanceState() 保留應用程式在裝置重新啟動狀態下的根活動狀態。

注意:只有在應用程式的根活動上設定這個屬性值時,該值才會影響您應用程式的行為。

persistAcrossReboots

系統會保留這個活動的狀態,還有返回堆疊上層各活動的狀態,後者的 persistableMode 屬性設為 persistAcrossReboots。如果活動沒有設為 persistAcrossRebootspersistableMode 屬性,或者是透過 Intent.FLAG_ACTIVITY_NEW_DOCUMENT 旗標啟動,系統就不會保留該活動,連帶也不會保留返回堆疊上層的所有活動。

當意圖在應用程式中載入 persistableMode 屬性設為 persistAcrossReboots 的活動時,該活動會在自身的 onCreate() 方法中接收 PersistableBundle 物件。因此,只要活動的 persistableMode 屬性設為 persistAcrossReboots,您就可以透過 onSaveInstanceState() 在裝置重新啟動時保留活動的狀態。

注意:即使是在應用程式根活動以外的活動上設定這個屬性值,該值仍會影響您應用程式的行為。

persistNever

系統不會保留活動的狀態。

注意:只有在應用程式的根活動上設定這個屬性值時,該值才會影響您應用程式的行為。

此屬性在 API 級別 21 中推出。

android:permission
客戶必須擁有的權限名稱來啟動該活動或者以其他方式讓它對意圖作出反應。如果 startActivity()startActivityForResult() 的呼叫端未獲授予指定權限,其意圖就不會傳遞至活動。

如果未設定這項屬性,系統會將 <application> 元素的 permission 屬性所設權限套用至該活動。如果未設定這兩個屬性,活動就不會受到權限保護。

如要進一步瞭解權限,請參閱應用程式資訊清單總覽的「權限」一節和「安全性提示」一文。

android:process
執行活動的程序名稱。一般來說,應用程式的所有元件都會在為應用程式建立的預設程序名稱中執行,因此您不需要使用這項屬性。但如有必要,您可以使用這項屬性覆寫預設程序名稱,將應用程式元件分散至多個程序。

如果指派給此屬性的名稱以半形冒號開頭 (:),系統會視需要建立一個該應用程式專屬的新程序,而活動會在該程序中執行。

如果程序名稱的開頭是小寫英文字元,活動會在採用該名稱的通用程序中執行 (前提是該程序具備相關權限)。這樣可讓不同應用程式中的元件共用程序,進而減少資源用量。

<application> 元素的 process 屬性可以為所有元件設定不同的預設程序名稱。

android:relinquishTaskIdentity
指定活動是否要將自身的任務識別碼交給任務堆疊中位置較高的其他活動。如果任務的根層級活動將此屬性設為 "true",則該任務會將基礎 Intent 替換為任務中下一個活動的基礎。

如果下一個活動也將此屬性設為 "true",則該活動會將基礎 Intent 讓給其在同一任務中啟動的任何活動。系統會繼續為每個活動執行此程序,直到遇到將此屬性設為 "false" 的活動為止。預設值為 "false"

此外,將此屬性設為 "true",也允許活動使用 ActivityManager.TaskDescription 更改「最近使用」畫面中的標籤、顏色和圖示。

android:resizeableActivity

指定應用程式是否支援 多視窗模式。您可以在 <activity><application> 元素中設定這個屬性。

如果將這項屬性設為 "true",使用者就能在分割畫面和任意形式模式下啟動活動。如果將這項屬性設為 "false",應用程式就無法在多視窗環境中進行測試或最佳化。系統可能仍會將活動置於套用相容模式的多視窗模式下。

此外,即使您將這項屬性設為 "false",也無法保證畫面 (例如子母畫面) 或其他螢幕上不會顯示其他處於多視窗模式下的應用程式。因此,設定這個旗標並不代表應用程式擁有專屬資源存取權。

如果應用程式指定的 API 級別為 24 以上,但您未指定這個屬性的值,則屬性值會預設為 "true"

如果應用程式指定的 API 級別為 31 以上,則此屬性在小螢幕和大螢幕上的運作方式會有所不同:

  • 大螢幕 (sw >= 600dp):所有應用程式皆支援多視窗模式。這項屬性會表明能否調整應用程式大小,而不是應用程式是否支援多視窗模式。設為 resizeableActivity="false" 時,應用程式會在必要時處於相容模式,以符合顯示尺寸。
  • 小螢幕 (sw < 600dp):如果 resizeableActivity="true" 以及活動的最小寬度與最小高度都符合多視窗模式的要求,則應用程式支援多視窗模式。如果 resizeableActivity="false",無論活動的最小寬度和高度如何,應用程式都不支援多視窗模式。

注意事項:裝置製造商可覆寫 API 級別 31 的行為。

這個屬性已新增至 API 級別 24。

注意事項:工作的根活動值會套用至該工作啟動的所有額外活動。也就是說,如果工作的根層級活動可以調整大小,系統就會將工作中的所有其他活動視為可調整大小。如果根層級活動無法調整大小,任務中的其他活動就無法調整大小。

android:screenOrientation

活動在裝置螢幕上的顯示方向。

在 Android 7.0 (API 級別 24) 以上版本中,如果活動處於多視窗模式,系統會忽略這個屬性的執行階段變更。

Android 12 (API 級別 31) 以上版本中,裝置製造商可以設定個別裝置螢幕 (例如折疊式裝置的平板電腦大小螢幕),藉此忽略螢幕方向規格,並強制設為僅限直向的應用程式在橫向螢幕上保持水平並加上黑邊,以確保應用程式在直向模式下仍具有直向顯示比例,同時提高應用程式的可用性。

這個值可以是下列任一字串:

"unspecified" 預設值。系統選擇方向。系統採用的政策以及在特定情境中所做的選擇,可能會因裝置而有所不同。
"behind" 方向會與活動堆疊中緊位於該活動下方的活動相同。
"landscape" 橫向(顯示的寬度大於高度)。
"portrait" 縱向(顯示的高度大於寬度)。
"reverseLandscape" 橫向方向與一般橫向相反。 已在 API 級別 9 中新增。
"reversePortrait" 直向方向與一般直向相反。 已在 API 級別 9 中新增。
"sensorLandscape" 橫向,但可根據裝置感應器調整為以一般/相反橫向顯示。即便使用者已鎖定感應器旋轉功能,還是會用到感應器。 已在 API 級別 9 中新增。
"sensorPortrait" 直向,但可根據裝置感應器調整為以一般/相反直向顯示。即便使用者已鎖定感應器旋轉功能,還是會用到感應器。然而,視裝置設定而定,可能無法支援上下旋轉。 已在 API 級別 9 中新增。
"userLandscape" 橫向,但可根據裝置感應器和使用者偏好設定調整為以一般/相反橫向顯示。已在 API 級別 18 中新增。
"userPortrait" 直向,但可根據裝置感應器和使用者偏好設定調整為以一般/相反直向顯示。然而,視裝置設定而定,可能無法支援上下旋轉。 已在 API 級別 18 中新增。
"sensor" 裝置方向感應器會決定螢幕方向。顯示的方向取決於使用者手持裝置的方式,方向會隨使用者旋轉裝置而改變。不過,某些裝置預設不會旋轉到全部四種可能的方向。如要使用全部四個方向,請使用 "fullSensor"。即使使用者已鎖定感應器旋轉功能,還是可以使用感應器。
"fullSensor" 裝置方向感應器會決定四個方向中的任一方向。這與 "sensor" 類似,區別在於無論裝置通常支援哪個方向,這個值允許四個可能方向中的任一方向。舉例來說,某些裝置通常不會使用反向直向或反向橫向,但這個值可啟用這些螢幕方向。已新增至 API 等級 9。
"nosensor" 在沒有參考實體方向感應器的情況下決定方向。系統會忽略感應器,因此畫面不會根據使用者移動裝置的方式旋轉。
"user" 使用者目前偏好的方向。
"fullUser" 如果使用者已鎖定感應器旋轉功能,此行為就與 user 相同,否則行為會與 fullSensor 相同,且允許使用四種可能的螢幕方向。已新增至 API 等級 18。
"locked" 將方向鎖定在目前的任意旋轉方向。已在 API 級別 18 中新增。

注意:當您宣告其中一個橫向或直向值時,即視為對活動執行的方向提出硬性要求。 因此,Google Play 等服務可以使用您宣告的值進行篩選,這樣一來,就只有支援活動所需方向的裝置才能使用您的應用程式。舉例來說,如果您宣告 "landscape""reverseLandscape""sensorLandscape",表示您的應用程式僅適用於支援橫向螢幕方向的裝置。

此外,請使用 <uses-feature> 元素明確宣告應用程式需要使用直向或橫向螢幕方向,例如 <uses-feature android:name="android.hardware.screen.portrait"/>。這是 Google Play 和其他支援篩選功能的服務提供的篩選行為,平臺本身無法控制在裝置僅支援特定螢幕方向時是否能安裝您的應用程式。

android:showForAllUsers

當裝置目前的使用者與啟動活動的使用者不同時,是否會顯示該活動。您可以將這個屬性設為常值 (例如 "true""false"),也可以將該屬性設為包含布林值的資源或主題屬性。

這是在 API 級別 23 中新增的屬性。

android:stateNotNeeded
設定活動能否在沒有儲存狀態的情況下終止並順利重新啟動。"true" 表示可在不參考其先前狀態的情況下重新啟動,"false" 表示需要參考其先前狀態。預設值為 "false"

通常,系統會為了節省資源而暫時關閉活動,但在這之前會呼叫活動的 onSaveInstanceState() 方法。這個方法會將活動目前的狀態儲存在 Bundle 物件中,然後在活動重新啟動後傳送至 onCreate()。如果這項屬性設為 "true",系統可能不會呼叫 onSaveInstanceState(),但會向 onCreate() 傳遞 null (而非 Bundle),就像活動第一次啟動時一樣。

"true" 設定表示可在沒有保留狀態的情況下重新啟動活動。例如,顯示主畫面的活動使用這項設定,確保活動因某種原因當機時不會遭到刪除。

android:supportsPictureInPicture

指定活動是否支援 子母畫面顯示。

android:taskAffinity
該活動具有相依性的工作。從概念上來說,具有相同相依性的活動屬於同一任務,從使用者的角度來看,則屬於同一「應用程式」。任務的相依性取決於任務根活動的相依性。

相依性決定了兩件事:其一是更改為活動父項的任務 (請參閱 allowTaskReparenting 屬性),其二是使用 FLAG_ACTIVITY_NEW_TASK 旗標啟動活動時,用於容納該活動的任務。

根據預設,應用程式中的所有活動都有相同的相依性。您可以設定這個屬性,以不同方式將活動分組,甚至可以將不同應用程式中定義的活動放在同一個任務中。若要指定該活動對任何工作都沒有相依性,請將其設定為空字串。

如果未設定這項屬性,活動就會繼承為應用程式設定的相依性。詳情請參閱 <application> 元素的 taskAffinity 屬性。應用程式預設相依性的名稱是在 build.gradle 檔案中設定的命名空間

android:theme
參照對定義活動整體主題的風格資源。這會自動設定活動的內容來使用這個 theme,也可能在活動啟動之前引發「啟動」動畫,用意是符合活動的實際外觀。

如果未設定這項屬性,活動會從 <application> 元素的 theme 屬性,繼承為應用程式整體設定的主題。如果未設定這項屬性,則會使用預設的系統主題。詳情請參閱「樣式與主題」一文。

android:uiOptions
活動 UI 的額外選項,必須是下列其中一個值。

說明
"none"沒有額外的 UI 選項。此為預設值。
"splitActionBarWhenNarrow"當水平空間受限時 (例如手機處於直向模式),在畫面底部新增一列,以便在「應用程式列」(又稱為「動作列」) 中顯示操作項目。應用程式列將分成畫面頂端的導航部分和底部的操作項目列,而不會以少量操作項目的形式顯示在畫面頂端。這表示操作項目和頂端的導覽及標題元素均能獲得適量空間。選單項目不會分割在兩個長條中,一律會一同顯示。

如要進一步瞭解應用程式列,請參閱「新增應用程式列」一文。

這是在 API 級別 14 中新增的屬性。

android:windowSoftInputMode
活動的主要視窗如何與含有螢幕電子鍵盤的視窗互動。此屬性的設定會影響以下兩項:
  • 當活動成為使用者關注的焦點時,要隱藏或顯示螢幕鍵盤。
  • 是否要將活動的主要視窗調整為較小尺寸,為螢幕鍵盤騰出空間,或者當視窗的一部分被螢幕鍵盤覆蓋時,是否要將其內容平移,顯示目前的焦點。

這項設定必須是下表所列的其中一個值,或一個 "state..." 值加上一個 "adjust..." 值的組合。在任一群組中設定多個值 (例如多個 "state..." 值) 均會產生未定義的結果。個別值會以直線 (|) 分隔,如以下範例所示:

<activity android:windowSoftInputMode="stateVisible|adjustResize" ... >

在這裡設定的值 ("stateUnspecified""adjustUnspecified" 除外) 會覆寫主題中設定的值。

說明
"stateUnspecified" 未指定螢幕鍵盤為隱藏或顯示狀態。系統會選擇合適的狀態,或是依主題的設定為準。

這是螢幕鍵盤行為的預設設定。

"stateUnchanged" 當活動出現在前景時,螢幕鍵盤會保持在最後所處的任何狀態 (無論是顯示或隱藏)。
"stateHidden" 當使用者選擇活動時,系統會隱藏螢幕鍵盤;選擇活動是指當使用者主動向前導覽到該活動,而不是因為離開其他活動而返回該活動。
"stateAlwaysHidden" 當活動的主要視窗已輸入焦點時,一律隱藏螢幕鍵盤。
"stateVisible" 當使用者選擇活動時,系統會顯示螢幕鍵盤;選擇活動是指當使用者主動向前導覽到該活動,而不是因為離開其他活動而返回該活動。
"stateAlwaysVisible" 當視窗收到輸入焦點時,即會看到螢幕鍵盤。
"adjustUnspecified" 未指定是要調整活動的主要視窗大小,為螢幕鍵盤騰出空間,還是要平移視窗內容,在畫面上顯示目前的焦點。系統會根據視窗內容是否有任何可以捲動內容的版面配置檢視區塊,自動選取其中一種模式。如果有這樣的檢視區塊,系統會假定可以透過捲動在小塊區域內顯示所有視窗內容,從而調整視窗大小。

這是主視窗行為的預設設定。

"adjustResize" 該活動的主視窗總是被調整大小,以便為螢幕上的螢幕鍵盤留出空間。
"adjustPan" 不透過調整活動的主要視窗大小,為螢幕鍵盤騰出空間,而是自動平移視窗內容,這樣鍵盤就絕不會遮擋目前的焦點,讓使用者隨時看到自己輸入的內容。通常這個做法的效果會比調整大小來得差,因為使用者可能需要關閉螢幕鍵盤,才能看到視窗被遮住的部分並與之互動。

這項屬性是在 API 級別 3 中導入。

導入版本:
所有屬性皆於 API 級別 1 導入,於 API 級別 3 中新增的 noHistorywindowSoftInputMode 除外。
另請參閱:
<application>
<activity-alias>