- 語法:
<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
」,每次使用者重新啟動任務時,系統都會導向任務的根活動中;不論使用者最後在任務中執行什麼操作,或是否利用「Back」或「Home」按鈕來離開任務,結果都會一樣。當值為「false
」時,任務在某些情況可能會清除其下所有活動 (請參閱alwaysRetainTaskState
屬性),但也有例外。舉例來說,某人在主畫面上啟動活動 P,然從該處前往活動 Q。接著,使用者按下「Home」,然後返回活動 P。使用者通常會看到活動 Q,因為這是他們最後在 P 任務中所做的活動。不過,如果 P 將這個旗標設為「
true
」,當使用者從主畫面啟動活動 P 時,系統會移除 P 上方的所有活動 (在本例中為 Q)。也就是說,使用者返回任務時只會看到 P。如果此屬性和
allowTaskReparenting
都為「true
」,則任何可重新父項的活動均會移至與其共用興趣相似目標對象的工作;然後按照上述步驟捨棄剩餘的活動。如未設定
FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
,系統會忽略這個屬性。 android:colorMode
要求在相容裝置上以廣色域模式顯示活動。在廣色域模式下,視窗可在
SRGB
以外的區域轉譯,顯示更加鮮豔的色彩。如果裝置不支援廣色域顯示,這個屬性就不會有任何作用。如要進一步瞭解如何以廣色模式顯示內容,請參閱「使用廣色內容增強圖像效果」。android:configChanges
- 列出活動可自行處理的設定變更。根據預設,當設定變更在執行階段發生,系統會關閉並重新啟動活動,如果用這個屬性來宣告設定,則會造成活動無法重新啟動,反而會保持運作,系統還會呼叫其
方法。onConfigurationChanged()
注意:請只在特殊情況下才使用這個屬性,以便提高應用程式的效能和回應速度。詳情請參閱「處理設定變更」一文。
以下任何或所有字串都是該屬性的有效值。多個值之間以「
|
」分隔,例如「locale|navigation|orientation
」。值 說明 「 density
」顯示密度已變更,表示使用者可能指定了不同的螢幕縮放比例,或者現已啟用其他螢幕。 已在 API 級別 24 中新增。
「 fontScale
」字型縮放比例係數已變更,表示使用者已選取新的全域字型大小。 「 keyboard
」鍵盤類型已變更,例如使用者已連接外部鍵盤。 「 keyboardHidden
」鍵盤的無障礙功能已變更,例如使用者採用了實體鍵盤。 「 layoutDirection
」版面配置方向已變更,例如從左到右 (LTR) 變更為由右到左 (RTL)。 已新增至 API 等級 17。
「 locale
」語言代碼已變更,表示使用者選取了新的語言,文字應以此語言顯示。 「 mcc
」IMSI 行動國家/地區代碼 (MCC) 已變更,SIM 卡已偵測到並更新 MCC。 「 mnc
」IMSI 行動網路識別碼 (MNC) 已變更,表示偵測到 SIM 卡並更新了 MNC。 「 navigation
」導覽類型 (軌跡球/Dpad) 已變更,(通常是不會發生)。 「 orientation
」螢幕方向已變更,表示使用者已旋轉此裝置。
注意:如果您的應用程式指定的是 Android 3.2 (API 級別 13) 或以上版本,也請一併宣告
"screenLayout"
和"screenSize"
設定,因為當裝置在直向和橫向模式間切換時,螢幕版面配置和螢幕大小可能會隨之變更。「 screenLayout
」螢幕版面配置已變更,表示現在啟用的可能是其他螢幕。 「 screenSize
」目前可用的螢幕大小已變更。 這代表目前可用尺寸相對於當前顯示比例的更改幅度,所以當使用者在橫向和直向之間切換時,這個值就會變動。
已新增至 API 等級 13。
「 smallestScreenSize
」實體螢幕大小已變更。 這代表了尺寸的變化,與方向無關,所以只有在實際的實體螢幕尺寸發生變化時才會改變,例如切換到外部顯示器。該設定的變化對應於 最小寬度 設定的變化。
已新增至 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
- 設定當前活動的沉浸模式設定。如果為該活動將
android:immersive
屬性在應用程式的資訊清單項目中設為true
,那麼即使在執行階段使用setImmersive()
方法變更沉浸模式,ActivityInfo.flags
成員的FLAG_IMMERSIVE
位元一律會是設定完成的狀態。 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()
指令,在這種情況下,系統會選擇其他任務;請參閱 taskAffinity 屬性)。FLAG_ACTIVITY_NEW_TASK
「
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
等其他模式不適合大多數應用程式使用,因為它們可能會形成使用者不熟悉的交互模型,而且與大多數其他應用有很大不同。無論您選擇哪種啟動模式,請確保在啟動過程中,以及使用「Back」按鈕從其他活動和任務返回該活動時,對活動進行可用性測試。
關於啟動模式及其與意圖旗標的互動的更多資訊,請參閱任務和反向堆疊文件。
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 (低記憶體裝置為 25);零則無效。此值必須為整數,例如 50。預設值為 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
」,則該任務會將基本意圖替換為任務中下一個活動的基本意圖。如果下一個活動也將此屬性設為「true
」,則該活動會將本身的基本意圖讓給其在同一任務中啟動的任何其他活動。系統會繼續為每個活動執行此程序,直到遇到將此屬性設為「false
」的活動為止。此屬性的預設值為「false
」。此屬性設置為「
true
」還允許活動使用ActivityManager.TaskDescription
更改總覽畫面 中的標籤、顏色和圖示。 resizeableActivity
-
指定應用程式是否支援 多視窗模式。您可以在
<activity>
或<application>
元素中設定這個屬性。如果將這個屬性設為 true,使用者就能以分割畫面和任意形式模式啟動活動。如果將屬性設為 false,應用程式就無法在多視窗環境中進行測試或最佳化。系統可能仍會將活動置於套用相容模式的多視窗模式之下。此外,即使您將這項屬性設為 True,也無法保證畫面 (例如子母畫面) 或其他螢幕上不會顯示其他處於多視窗模式下的應用程式。因此,設定這個旗標並不能確保應用程式具有專屬資源存取權。
如果應用程式指定的 API 級別為 24 以上,但您未指定這個屬性的值,則屬性值會預設為 true。
如果應用程式指定的 API 級別為 31 以上,則此屬性在小螢幕和大螢幕上的運作方式會有所不同:
- 大螢幕 (sw >= 600dp):所有應用程式皆支援多視窗模式。這個屬性可指出應用程式能否調整大小 (不適用於應用程式是否支援多視窗模式)。設為
resizeableActivity="false"
時,應用程式會在必要時處於相容模式,以符合顯示尺寸。 - 小螢幕 (sw < 600dp):如果
resizeableActivity="true"
以及活動的最小寬度與最小高度符合在多視窗需求中,則應用程式支援多視窗模式。如果設為resizeableActivity="false"
,無論活動的最小寬度和高度如何,該應用程式不支援多視窗模式,。
注意事項:裝置製造商可覆寫 API 級別 31 的行為。
這個屬性已新增至 API 級別 24。
注意事項:工作的根活動值會套用至該工作啟動的所有額外活動。也就是說,如果工作的根層級活動可以調整大小,系統就會將工作中的所有其他活動視為可調整大小。如果根層級活動無法調整大小,工作中的其他活動就無法調整大小。
- 大螢幕 (sw >= 600dp):所有應用程式皆支援多視窗模式。這個屬性可指出應用程式能否調整大小 (不適用於應用程式是否支援多視窗模式)。設為
android:screenOrientation
- 活動在裝置上的顯示方向。如果活動是在 多視窗模式 執行,系統會忽略這個屬性。
這個值可以是下列任一字串:
「 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
」方向是由 4 種螢幕方向其中任何一個方向決定。這類似於 "sensor"
,除了這允許4種可能的螢幕方向中的任何一種,而不管裝置運作通常為何(例如,一些裝置通常不會使用反向直向或反向橫向,但這可以實現這些目的)。已新增至 API 等級 9。「 nosensor
」方向是指在沒有實際方向感應器的情況下所決定。感應器會被忽略,因此不會根據使用者移動裝置的方式旋轉。 「 user
」使用者目前偏好的方向。 「 fullUser
」如果使用者已鎖定感應器旋轉功能,此行為就與 user
相同,否則行為會與fullSensor
相同,且可以指定 4 種可能的螢幕方向。已新增至 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
」設定可確保活動在沒有保留狀態的情況下重新啟動。例如,顯示主畫面的活動可以使用這項設定,確保活動因某種原因當機時不會遭到刪除。 supportsPictureInPicture
-
指定該活動是否支援子母畫面顯示。
這是在 API 級別 24 中新增的屬性。
android:taskAffinity
- 該活動具有相依性的工作。從概念上來說,具有相同相依性的活動屬於同一任務 (從使用者的角度來看,則屬於同一「應用程式」)。任務的相依性取決於任務根活動的相依性。
相依性決定了兩件事,其一是將活動重新設為父項的任務 (請參閱
allowTaskReparenting
屬性),其二是透過
旗標啟動活動時,用於容納該活動的任務。FLAG_ACTIVITY_NEW_TASK
根據預設,應用程式中的所有活動都有相同的相依性。您可以設定這個屬性,以不同方式將活動分組,甚至可以將不同應用程式中定義的活動放在同一個任務中。若要指定該活動對任何工作都沒有相依性,請將其設定為空字串。
如果這個屬性尚未設定,活動就會沿用針對應用程式所設定的相依性 (請參閱該
<application>
元素的taskAffinity
屬性)。應用程式預設相依性的名稱是在build.gradle
檔案中設定的命名空間。 android:theme
- 參照對定義活動整體主題的風格資源。這將自動設定活動的內容來使用這個主題 (請參閱
),也可能在活動啟動之前引發「啟動」動畫 (以利更佳符合活動的實際外觀)。setTheme()
如果這個屬性尚未設定,活動就會繼承針對應用程式整體設定的主題 (源自
<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-02-25 (世界標準時間)。
[]
[]