- 語法:
<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: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
指定活動的色彩模式,可指定為
hdr
或wideColorGamut
。如果設為
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_DOCUMENT
和FLAG_ACTIVITY_MULTIPLE_TASK
旗標的效果相同。"none"
該活動不會為活動建立新任務。這是預設值,只有在已設定 FLAG_ACTIVITY_NEW_TASK
時才會建立新任務。「最近使用」畫面會以預設方式處理活動:這個畫面會顯示應用程式的單一任務,無論使用者上次叫用哪一項活動,都能繼續執行該任務。"never"
即使 Intent 包含 FLAG_ACTIVITY_NEW_DOCUMENT
,系統也不會在新文件中啟動這項活動。這項設定會覆寫FLAG_ACTIVITY_NEW_DOCUMENT
和FLAG_ACTIVITY_MULTIPLE_TASK
旗標的行為 (如果活動中已設定這類標記),且「最近使用」畫面會顯示應用程式的單一任務,無論使用者上次叫用哪一項活動,都能繼續執行該任務。注意:如果值不是
"none"
和"never"
,活動必須以launchMode="standard"
定義。如未指定這項屬性,則會使用documentLaunchMode="none"
。 android:enabled
- 表示系統可否建立活動的例項。
"true"
表示可以,"false"
表示不可以。預設值為"true"
。<application>
元素提供專屬的enabled
屬性,適用於包括活動在內的所有應用程式元件。<application>
和<activity>
屬性都必須為"true"
,因為兩者都採用這個預設值時,系統就能建立活動的例項。只要其中一個是"false"
,就無法建立例項。 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、Shader 和 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_TASK
或FLAG_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
。如果活動沒有設為persistAcrossReboots
的persistableMode
屬性,或者是透過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。
注意:任務的根活動值會套用至該任務啟動的所有其他活動。也就是說,如果任務的根層級活動可以調整大小,系統就會將任務中所有其他活動視為可調整大小。如果根層級活動無法調整大小,任務中的其他活動就無法調整大小。
- 大螢幕 (sw >= 600dp):所有應用程式皆支援多視窗模式。這項屬性會表明能否調整應用程式大小,而不是應用程式是否支援多視窗模式。如果
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 中新增的
noHistory
和windowSoftInputMode
除外。 - 另請參閱:
<application>
<activity-alias>
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間:2023-11-11 (世界標準時間)。
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"缺少我需要的資訊"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"過於複雜/步驟過多"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"過時"
},{
"type": "thumb-down",
"id": "translationIssue",
"label":"翻譯問題"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"示例/程式碼問題"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"其他"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"容易理解"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"確實解決了我的問題"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"其他"
}]