- 語法:
<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
(或包含FLAG_ACTIVITY_CLEAR_TOP
的up
意圖),則父項會移至堆疊頂端,並保留其狀態。瀏覽意圖是由父項活動的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>
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2023-01-27 UTC.
[]
[]