Android 會針對宣告方向或宣告的應用程式啟用相容性模式 大小限制。相容性模式可確保應用程式在 大螢幕裝置和折疊式手機,但會降低可用性。
個別應用程式覆寫值可讓裝置製造商變更 以改善使用者體驗,或防止應用程式異常終止 。
參考裝置
由於下列裝置出現異常,因此可能會要求個別應用程式覆寫設定 應用程式尚未全面支援的設定或設定:
- 平板電腦:某些平板電腦 (例如 Pixel Tablet) 的自然方向。
橫向裝置處於自然方向時
可退貨:
Display#getRotation()
Surface.ROTATION_0
。如果應用程式假設ROTATION_0
為直向, 應用程式版面配置和相機預覽畫面可能與裝置螢幕不相符。 - 橫向摺疊式裝置:部分摺疊式裝置 (例如 Pixel Fold) 已 折疊時的直向模式,展開時則為橫向。 如果應用程式假設展開的螢幕方向為直向,則閃爍 迴圈或版面配置問題都可能會發生問題。
- 折疊式手機:展開的折疊式手機通常為直向。 方向。但摺疊時,手機通常在 橫向。應用程式必須找出並配合 螢幕的方向
常見相容性問題
應用程式異常終止問題,通常是因為應用程式方向而發生相容性問題 限制、大小調整與顯示比例的限制、未正確處理 相機預覽方向和濫用的 API。
黑邊
應用程式加上黑邊後,即可置中顯示在螢幕中央,或 方便存取霧面 (實心長條 「模糊化的桌布」) 填滿未使用的顯示區域,會沿著兩側或頂端填滿,以及 應用程式底部。
大螢幕裝置上經常出現黑邊,這是因為 裝置的螢幕顯示比例通常與標準尺寸不同 手機,其中大部分是為大部分應用程式所設計。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/letterboxing.png?authuser=0000&hl=zh-tw)
圖 1. 在橫向的平板電腦和摺疊式裝置上,僅限直向的應用程式會加上黑邊。
問題
應用程式已修正,因此不支援所有顯示設定 螢幕方向、固定長寬比,或是無法調整大小
可控制應用程式的方向和大小調整設定包括: 包括:
screenOrientation
:指定 應用程式。應用程式也可以利用Activity#setRequestedOrientation()
。resizeableActivity
:指出系統能否 配合不同大小的視窗調整應用程式大小。在 Android 11 (API 級別) 中 30) 以下版本,則指定應用程式是否支援多視窗模式。啟用 Android 12 (API 級別 31) 以上版本指定應用程式是否支援 在小螢幕上使用多視窗模式 (精簡 視窗大小類別)。在 Android 12 以上版本中 支援大螢幕 (中等或展開視窗) 的多視窗模式 大小類別)。maxAspectRatio
:指定顯示比例上限 應用程式是否支援這項功能只有resizeableActivity
設為「false
」的應用程式才能 設定「maxAspectRatio
」。minAspectRatio
:指定最小顯示比例 應用程式是否支援這項功能只有resizeableActivity
設為「false
」的應用程式才能 設定「minAspectRatio
」。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/letterboxing_issue.png?authuser=0000&hl=zh-tw)
在橫向裝置上難以使用的僅限直向應用程式。
最佳化
應用程式應支援所有裝置和多視窗模式顯示畫面 螢幕方向和大小移除所有方向和固定顯示比例 對於應用程式版面配置和應用程式資訊清單檔案的限制。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/letterboxing_optimization.png?authuser=0000&hl=zh-tw)
應用程式支援所有裝置方向。
相容性暫時替代方案
採用固定方向或固定顯示比例的視窗執行 應用程式未直接支援視窗大小或方向,例如 Android 會為應用程式加上黑邊,以維持連續性。
從 Android 12 (API 級別 31) 開始,從 Android 12L (API 級別 32) 開始。 這個平台會為加上黑邊的應用程式套用各種強化功能裝置 會實作使用者介面改善項目您無須執行其他操作 以便享有這些改良服務
Android 12 (API 級別 31) 推出了以下外觀改善項目, 可以透過裝置製造商設定:
- 圓角:讓應用程式視窗的四個角更圓滑。
- 系統資訊列透明度:與 應用程式是半透明的,讓列上的圖示在 上下黑邊背景
- 可設定的顯示比例:可調整應用程式的顯示比例 改善應用程式的外觀
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/enhanced_letterboxing.png?authuser=0000&hl=zh-tw)
圖 2. 加上黑邊且 UI 經過改善的應用程式。
Android 12L (API 級別 32) 新增了下列功能改善項目:
可設定的位置:在大螢幕上,裝置製造商可以 將應用程式放在螢幕的左側或右側 才能輕鬆上手
經過重新設計的重新啟動按鈕:裝置製造商可啟動重新啟動按鈕 全新外觀的大小相容性模式按鈕 方便使用者辨識產品
Android 13 (API 級別 33) 新增了使用者說明對話方塊,告訴您如何放置 應用程式會加上黑邊,或是在分割畫面模式中加上黑邊:
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/enhanced_letterboxing_user_dialog.png?authuser=0000&hl=zh-tw)
圖 3. 加上黑邊的應用程式顯示使用者說明對話方塊。
大小相容性模式
大小相容性模式是包含重新啟動控制項的黑邊效果。 控制項可讓使用者重新啟動應用程式,並重新繪製顯示畫面。Android 叫用 如果系統判定應用程式無法調整大小,就會採用大小相容性模式。如果 活動會移至與活動的容器不相容的顯示容器 可能會重新調整應用程式大小,以填滿裝置 至少 1 個維度
可觸發大小相容性模式的裝置設定包括:
- 裝置旋轉
- 摺疊式裝置摺疊或展開
- 切換全螢幕和分割畫面顯示模式
問題
大小相容性模式通常適用於符合以下條件的活動: 並設定為 (或由系統決定) 但無法調整大小
系統判定您的應用程式可調整大小,不會調整大小 相容性模式—只要符合下列任一條件即可:
- 能使用
resizeableActivity="true"
調整大小 - 支援子母畫面 (PIP) 模式
- 已嵌入
- 已套用以下應用程式的
FORCE_RESIZE_APP
個別應用程式覆寫值: 裝置製造商 (系統會忽略應用程式所設定的屬性)
如果應用程式「不」符合任一條件,即視為未 可調整大小,且可進入大小相容性模式。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/size_compatibility_mode_issue.gif?authuser=0000&hl=zh-tw)
在多視窗模式下,無法調整大小的應用程式異常終止。
最佳化
應用程式應支援所有顯示大小。設定應用程式的
<activity>
的 android:resizeableActivity
屬性
或<application>
加入true
應用程式資訊清單。為應用程式設計回應式/自動調整式版面配置。如要
資訊,請參閱
支援不同的螢幕大小和支援
多視窗模式。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/size_compatibility_mode_optimization.gif?authuser=0000&hl=zh-tw)
應用程式適用於所有視窗大小。
相容性暫時替代方案
如果系統判定 只要將應用程式重新調整以填滿整個畫面, 顯示視窗。系統會顯示重新啟動控制項 重新建立應用程式程序、重新建立活動 螢幕。請參閱「程序和執行緒總覽」。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/size_compatibility_mode_workaround.gif?authuser=0000&hl=zh-tw)
在橫向模式下,僅限直向的應用程式會加上黑邊,並由重新啟動控制項調整大小。
閃爍迴圈
如果應用程式不支援所有顯示方向,可能會重複執行 在設定變更時要求新的方向、建立 讓螢幕閃爍或應用程式無限旋轉的無限迴圈。
問題
在 Android 12 (API 級別 31) 以上版本中,裝置製造商可以設定
忽略應用程式指定的方向限制,而忽略這類限制
強制執行相容性模式舉例來說,摺疊式裝置可能會忽略
活動的 android:screenOrientation="portrait"
設定當裝置顯示在橫向的平板電腦大小上時
內螢幕。
如果系統忽略應用程式的方向限制,應用程式可透過程式輔助方式
設定其方向,方法是呼叫
Activity#setRequestedOrientation()
。通話
如果應用程式未處理設定變更,就會觸發應用程式重新啟動作業 (請參閱
處理設定變更)。在
重新啟動,應用程式的方向限制會再次遭到忽略,應用程式會重複
呼叫 setRequestedOrientation()
,呼叫會觸發應用程式的重新啟動作業,且
而是在自我循環迴圈中播放
另一個可能發生此問題的方式
自然方向 (「一般」方向為
是橫向 (也就是呼叫
Display#getRotation()
可退貨
Surface.ROTATION_0
,裝置採用橫向模式時
比例)。過去應用程式假設 Display.getRotation() =
Surface.ROTATION_0
表示裝置為直向,但這並非
一律將畫面放在 Android 上
例如某些摺疊式裝置的內螢幕
在某些平板電腦上
在摺疊式裝置內螢幕上橫向的應用程式,可能會檢查
螢幕旋轉,接收 ROTATION_0
的值,假設自然方向為
裝置直向,然後呼叫
setRequestedOrientation(
ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
敬上
)
可重新設定應用程式版面配置。應用程式重新啟動後 (橫向模式)
否則可能會再次檢查螢幕旋轉情形,並將值設為
ROTATION_0
,撥號
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT)
和
就能繼續無限迴圈
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/flickering_loops_issue.gif?authuser=0000&hl=zh-tw)
在直向螢幕上,僅限橫向的應用程式會重複呼叫 Activity#setRequestedOrientation()
。
最佳化
應用程式「不得」執行下列操作:
- 如要設定預設方向,請使用
Activity#setRequestedOrientation()
在 活動onCreate()
方法,因為方向要求可 未處理的設定變更意外觸發 - 假設裝置的自然方向 (
ROTATION_0
) 為直向 - 請根據與目前視窗大小無關的信號設定方向,例如
以
Display#getRotation()
的身分使用,FoldingFeature
或已淘汰的 API。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/flickering_loops_optimization.gif?authuser=0000&hl=zh-tw)
應用程式會處理設定變更,且沒有方向限制,因此不會進入閃爍迴圈。
相容性暫時替代方案
Android 會忽略在下列情況下對 Activity#setRequestedOrientation()
的呼叫
情境:
活動已從之前對方法的呼叫重新啟動,或 啟用相機相容性強制旋轉處理功能 (請參閱相機 。
裝置製造商可將這個行為套用至含有
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
。活動在一秒內發出超過兩個方向要求 表示已發生迴圈。從迴圈中選擇要求中,Android 會使用 可將應用程式顯示區域放到最大。
裝置製造商可將這個行為套用至含有
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
。
相機預覽
相機應用程式的相機預覽畫面 (或觀景窗) 可能沒有對齊或變形 在平板電腦、筆電和摺疊式裝置上運作
問題
Android 相容性定義說明文件指出 相機影像感應器「必須經過調整,確保相機的長邊 對齊螢幕的長邊。」
應用程式通常會假設裝置方向和相機感應器方向 縱向—適用於標準行動電話的合理假設。不過 平板電腦和筆記型電腦的自然方向,以及這類裝置的相機感應器 橫向。此外,摺疊式裝置等新板型規格可以 以及多個不同方向的相機感應器
以應用程式未預期的相機方向啟動活動,或 切換不同的相機或裝置螢幕 (適用於摺疊式裝置) 可能會造成 相機預覽畫面未對齊或變形。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/camera_preview_issue.png?authuser=0000&hl=zh-tw)
大螢幕摺疊式裝置上未對齊和變形的相機預覽畫面。
最佳化
相機應用程式必須正確識別及管理裝置方向和相機 感應器方向,以正確對齊及縮放相機預覽畫面。 應用程式必須計算裝置旋轉、感應器旋轉,以及螢幕或視窗 然後將結果套用至相機預覽畫面。如需詳細 指引,請參閱「相機預覽」和「相機簡介 觀景窗。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/camera_preview_optimization.png?authuser=0000&hl=zh-tw)
在所有裝置方向上,相機預覽畫面皆正確對齊及縮放。
相容性暫時替代方案
Display#getRotation()
時,裝置處於自然方向
會傳回 Surface.ROTATION_0
。系統會計算
CameraCharacteristics.SENSOR_ORIENTATION
敬上
以裝置自然方向為準Android 會對齊
直向僅限直向的應用程式,會依照裝置的自然方向呈現,
就是大多數應用程式的期待此外,Android 也會裁剪相機感應器的圖像
感應器方向為橫向,且相機預覽畫面為直向。具體來說
解決方法如下:
為僅限直向的應用程式強制旋轉相機預覽畫面:應用程式 如果限制為直向,則會預期裝置的自然方向 並將相機感應器方向設為直向不過在 Android 12 中 (API 級別 31) 以上版本,如果應用程式方向為 裝置製造商會忽略方向規格。
當僅限直向的應用程式連上相機時,Android 會強制 會旋轉應用程式,將應用程式的直向視窗對齊 以及裝置方向
在部分平板電腦上 (請參閱參考裝置):應用程式 直向視窗會旋轉為全螢幕直向視窗,對齊 裝置的自然方向強製完成後,應用程式就會佔據整個螢幕畫面 並輪替金鑰
平板電腦 - 強制旋轉僅限直向的應用程式。
摺疊式裝置的橫向內螢幕 (請參閱參考資料 裝置),則僅限直向的活動會旋轉為 對齊展開後的自然方向應用程式: 強制旋轉後會加上黑邊
摺疊式裝置 - 強制旋轉僅限直向的應用程式。應用程式也加上了黑邊。
內側前置鏡頭裁剪:部分內側前置鏡頭感應器 摺疊式裝置處於橫向模式。除了強制旋轉 摺疊式內螢幕的相機預覽畫面,Android 會裁剪內側前方 (橫向) 相機視野,讓感應器擷取相反的視角 以及裝置螢幕方向
強制重新整理相機預覽畫面:系統會循環顯示活動
onStop()
和onStart()
(預設) 方法,或是onPause()
和onResume()
(套用於 OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE 強制旋轉後的個別應用程式覆寫值,確保相機預覽畫面 正確顯示。顯示比例縮放:系統會動態變更 將相機預覽畫面強制旋轉至更高的最小顯示比例 確保相機預覽畫面正確縮放。
如果應用程式可處理相機預覽畫面,應用程式開發人員可以覆寫這些解決方法 正確。請參閱「個別應用程式覆寫值」。
經常遭到濫用的 API
Android 現已支援多視窗模式等功能 折疊式裝置等裝置 舊版 API 已淘汰,並由 適用於所有螢幕尺寸和裝置的最新版 API 。不過,已淘汰的 API 仍可用於舊版 相容性。
部分 View
API 是為特殊用途而設計,採用的不是最適合
就能輕鬆理解開發人員的需求
問題
開發人員繼續使用已淘汰的 Display
API,並錯誤假設
API 會傳回應用程式的邊界,而非裝置顯示區域的邊界。或開發人員
錯誤地使用特殊用途的 View API,來取得一般顯示指標
這會導致在應用程式視窗過後,重新調整 UI 元素的位置錯誤
調整事件大小,導致版面配置問題。
已淘汰且經常遭到濫用的 Display API:
若需更多資訊,請參閲 支援多視窗模式。
不當的 View API:
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/misused_APIs_issue.png?authuser=0000&hl=zh-tw)
已淘汰的 API 錯誤計算應用程式邊界,導致應用程式內容未顯示在畫面上。
最佳化
請勿依賴實體螢幕尺寸來決定 UI 元素位置。遷移
根據 WindowMetrics
將應用程式轉移至 API,包括:
WindowManager
API:
平台:
Jetpack:
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/misused_APIs_optimization.png?authuser=0000&hl=zh-tw)
API 正確計算應用程式視窗指標。
相容性暫時替代方案
兩項覆寫值會調整已淘汰的 Display
API 和濫用的 View
API,
傳回應用程式邊界:
「Display
」的ALWAYS_SANDBOX_DISPLAY_APIS
API;OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS
適用於 View
API根據預設,ALWAYS_SANDBOX_DISPLAY_APIS
適用於大小相容性模式的應用程式。
透明活動
透明活動是透明背景樣式的結果, 範例:
<style name="Transparent" parent="AppTheme">
<item name="android:windowIsTranslucent">true</item>
<item name="android:windowBackground">@android:color/transparent</item>
</style>
與對話方塊相關的主題 (例如 Theme.MaterialComponents.Dialog
) 可
加入的樣式會將活動設為透明。
透明活動不會涵蓋所有可用的顯示空間, 難以管理,因為可用的顯示區域會因 例如裝置旋轉、裝置摺疊及展開 多視窗模式。
問題
透明活動應符合第一個不透明活動的邊界 在工作活動堆疊中的透明活動下方。不過 會啟動權限對話方塊的活動可能是 trampoline (啟動另一個活動後消失的活動);和 因此,系統無法判定 Trampoline 活動邊界 會啟動透明權限對話方塊活動
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/transparent_activities_issue.png?authuser=0000&hl=zh-tw)
由於活動是從 Trampoline 啟動,因此對話方塊的位置有誤。
最佳化
透明活動會從最頂層不透明的活動繼承限制 活動堆疊中位於這些活動下方的活動。不透明活動 適用於透明活動的整個生命週期 刪除映像檔因此,請勿從以下應用程式啟動權限要求: 彈跳床活動。
如果 Trampoline 活動啟動權限要求,使用者可能不在 可以看到權限對話方塊,因為 Trampoline 活動會 會在使用者有機會回應對話方塊之前刪除;而 對話方塊活動的維度和位置 不正確。
應用程式應一律從要保留的活動啟動權限要求 ,直到使用者做出權限決定為止。
圓角
由於樣式指定了背景,因此活動可以透明 或活動內容未填滿可用空間 顯示空間如果透明活動填滿可用的顯示空間, 當設定成 並由裝置製造商進行但如果是透明活動 (例如 權限對話方塊) 未填滿可用空間,您可以自行決定 是否套用圓角。
權限對話方塊不會填滿可用的顯示空間,因為對話方塊 版面配置通常會使用 LayoutParams.WRAP_CONTENT LayoutParams.MATCH_PARENT。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/transparent_activities_optimization.png?authuser=0000&hl=zh-tw)
圓角的對話方塊已正確放置在可見的啟動活動上。
相容性暫時替代方案
請持續顯示啟動對話方塊活動,直到使用者 回應對話方塊。
系統會確保透明活動從 活動堆疊中透明活動底下的第一個不透明活動 包含與下列項目相關的限制:
- 大小相容性模式
- 方向
- 顯示比例
Unity 遊戲
Unity 遊戲會在 Android 全螢幕或多視窗模式下執行。不過 許多 Unity 遊戲在出現應用程式時失去焦點,並停止繪製內容 多視窗模式。
問題
Unity 已新增 Resizable Window
選項,以便支援 Android 上的多視窗模式。不過
初始實作在未對活動生命週期內的活動生命週期做出反應時,
多視窗模式
UnityPlayer,在應用程式失去焦點時暫停播放。播放器轉譯
黑色畫面,或是遊戲的最後一個凍結影格只有在下列情況才會繼續遊戲進度:
使用者輕觸螢幕許多使用 Unity 引擎的應用程式都面臨這個問題,
在多視窗模式下會顯示為黑色視窗。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/unity_games_issue.gif?authuser=0000&hl=zh-tw)
遊戲在多視窗模式下失去焦點,顯示為黑色視窗。
最佳化
請將 Unity 升級至 2019.4.40 以上版本,然後重新匯出遊戲。保留
已勾選「Resizable Window
」選項
Android Player 設定,否則
即使遊戲完整顯示
多視窗模式。
![](https://developer.android.com/static/images/guide/practices/compatibility-mode/unity_games_optimization.gif?authuser=0000&hl=zh-tw)
即使未處於焦點,遊戲也能在多視窗模式下正確顯示內容。
相容性暫時替代方案
裝置製造商則可將
OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS
敬上
針對個別應用程式覆寫值,以在
多視窗模式。此覆寫值可讓活動重新繪製內容,並
而非顯示黑畫面
測試應用程式相容性問題
如要測試應用程式,瞭解應用程式在不同板型規格上的行為,請採取以下步驟: 善用以下資源:
- 裝置串流:在正式版裝置 (包括 參考裝置),請參閱 採用 Firebase 技術的 Android 裝置串流
- Android Studio Hedgehog 中的模擬器:瞭解如何建立 參考裝置的模擬器,詳情請參閱 建立及管理虛擬裝置
- Android Studio 大小調整模擬器:瞭解如何存取 裝置,請參閱「在 Android Emulator 上執行應用程式」
已加上黑邊
請確認每個活動都能使用應用程式可用的所有顯示空間。首先,請在測試資料夾中宣告下列程式碼:
Kotlin
fun Activity.isLetterboxed() : Boolean { if (isInMultiWindowMode) return false val wmc = WindowMetricsCalculator.getOrCreate() val currentBounds = wmc.computeCurrentWindowMetrics(this).bounds val maxBounds = wmc.computeMaximumWindowMetrics(this).bounds val isScreenPortrait = maxBounds.height() > maxBounds.width() return if (isScreenPortrait) { currentBounds.height() < maxBounds.height() } else { currentBounds.width() < maxBounds.width() } }
Java
public boolean isLetterboxed(Activity activity) { if (activity.isInMultiWindowMode()) { return false; } WindowMetricsCalculator wmc = WindowMetricsCalculator.getOrCreate(); Rect currentBounds = wmc.computeCurrentWindowMetrics(activity).getBounds() Rect maxBounds = wmc.computeMaximumWindowMetrics(activity).getBounds(); boolean isScreenPortrait = maxBounds.height() > maxBounds.width(); return (isScreenPortrait) ? currentBounds.height() < maxBounds.height() : currentBounds.width() < maxBounds.width(); }
然後執行測試來斷言行為,確認目標活動不會 上下黑邊:
Kotlin
@get:Rule val activityRule = ActivityScenarioRule(MainActivity::class.java) @Test fun activity_launched_notLetterBoxed() { activityRule.scenario.onActivity { assertThat(it.isLetterboxed()).isFalse() } }
Java
@Rule public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class); public void activity_launched_notLetterBoxed() { try (ActivityScenario<MainActivity> scenario = ActivityScenario.launch(MainActivity.class)) { scenario.onActivity(activity -> { assertThat(isLetterboxed(activity)).isFalse(); }); } }
在理想情況下,請只執行這種測試,直到測試傳遞並宣告應用程式的 活動會佔用應用程式的整個顯示空間。測試應用程式 以確保行為一致。
個別應用程式覆寫值
Android 提供的覆寫值會變更已設定的應用程式行為。適用對象
舉例來說,FORCE_RESIZE_APP
覆寫值會指示
讓系統略過大小相容性模式,將應用程式調整為適合螢幕的大小
即使 resizeableActivity="false"
是
應用程式資訊清單中指定的 Pod
裝置製造商會將覆寫值套用到特定或所有應用程式 特定的大螢幕裝置在 Android 14 (API 級別 34) 以上版本中,使用者 可以透過裝置設定套用覆寫值。
使用者個別應用程式覆寫值
在 Android 14 以上版本中,設定選單可讓使用者變更長寬比 應用程式的比例大螢幕裝置,如參考資料 裝置會實作選單。
選單中會列出裝置上安裝的所有應用程式。使用者選擇 應用程式,然後將應用程式顯示比例設為 3:4、1:1、全螢幕或其他值 設定。使用者也可以將顯示比例重設為 應用程式的預設值,這已在應用程式資訊清單中指定。
應用程式可透過設定下列 PackageManager.Property
標記,選擇不採用相容性覆寫設定:
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE
如要選擇不採用使用者顯示比例相容性覆寫功能,請新增屬性 然後將值設為
false
:<application> <property android:name="android.window. PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE" android:value="false" /> </application>
您的應用程式將從裝置設定的應用程式清單中移除。位使用者 將無法覆寫應用程式的顯示比例
將屬性設為
true
不會產生任何影響。PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE
如何停用使用者顯示比例相容性的全螢幕選項 請將這個屬性加入應用程式資訊清單,並將值設為
false
:<application> <property android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE" android:value="false" /> </application>
全螢幕選項會從以下的顯示比例選項清單中移除: 裝置設定。使用者無法在
將這項屬性設為
true
不會產生任何影響。
為應用程式所有螢幕進行最佳化調整:請勿在以下平台設定顯示比例限制: 使用視窗大小類別以支援不同的 配合可用的顯示空間大小來設計版面配置。
個別應用程式的裝置製造商覆寫值
裝置製造商會在特定裝置上,依個別應用程式套用覆寫值。 參照裝置可能會將部分覆寫值套用到 都能支援多種應用程式
應用程式可選擇不採用大部分的覆寫值 (請參閱個別應用程式 覆寫值表格)。
您可以使用相容性設定,在啟用或停用覆寫值的情況下測試應用程式 架構 (請參閱相容性架構工具)。 覆寫值一旦啟用,就會套用至整個應用程式。
您也可以使用 Android Debug Bridge (ADB) 來啟用或 並決定應用程式要套用哪些覆寫值
請按照以下說明啟用或停用覆寫值:
adb shell am compat enable/disable <override name/id> <package>
針對參照裝置,檢查哪些覆寫值適用於 應用程式:
adb shell dumpsys platform_compat | grep <package name>
下表列出可用的覆寫值並指引 將應用程式最佳化,讓應用程式不需仰賴覆寫值。您可以新增 屬性標記,即可選擇不採用部分覆寫值。
個別應用程式覆寫值 | |||
---|---|---|---|
類型 | 名稱 | ID | 說明 |
大小調整 | FORCE_RESIZE_APP | 174042936 | 在設定變更時,為應用程式略過大小相容性模式。 |
FORCE_NON_RESIZE_APP | 181136395 | 在設定變更時,強制應用程式進入大小相容性模式。 | |
顯示比例 | OVERRIDE_MIN_ASPECT_RATIO | 174042980 | 把關型覆寫值,必須設為啟用才能套用其他顯示比例覆寫值。 |
OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY | 203647190 | 啟用此覆寫值時,覆寫範圍會限制為僅限直向的活動。預設為啟用。 | |
OVERRIDE_MIN_ASPECT_RATIO_MEDIUM | 180326845 | 將最小顯示比例變更為 3:2。 | |
OVERRIDE_MIN_ASPECT_RATIO_LARGE | 180326787 | 將最小顯示比例變更為 16:9。 | |
OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN | 208648326 | 配合螢幕大小或分割畫面顯示比例的 50%,變更最小顯示比例。 | |
OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN | 218959984 | 停用最小顯示比例覆寫值,讓應用程式在裝置直向時以全螢幕顯示。 | |
方向 | OVERRIDE_ANY_ORIENTATION | 265464455 | 啟用可覆寫任何方向的功能。 |
OVERRIDE_ANY_ORIENTATION_TO_USER | 310816437 | 覆寫方向、大小調整和顯示比例限制。 | |
OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT | 265452344 | 在活動未定義方向時,將方向覆寫為直向。 | |
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR | 265451093 | 在活動未定義方向時,將方向覆寫為 nosensor (使用裝置的自然方向)。 |
|
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE | 266124927 | 將僅限橫向的應用程式旋轉 180 度。 | |
OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA | 265456536 | 限制只在應用程式連上相機時覆寫方向。 | |
OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION | 255940284 | 在工作以全螢幕顯示時 (包含加上黑邊時),將顯示畫面設為固定的橫向自然方向。 | |
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION | 254631730 | 忽略應用程式的方向要求,避免旋轉無限迴圈。 | |
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED | 273509367 | 在活動重新啟動時,忽略重複的方向要求。如果 Android 偵測到應用程式正在一秒內要求至少兩個新方向,系統就會視為無限迴圈,並套用此覆寫值。 | |
OVERRIDE_RESPECT_REQUESTED_ORIENTATION | 236283604 | 停用裝置製造商忽略方向要求的設定,避免加上黑邊。 | |
沙箱 API | NEVER_SANDBOX_DISPLAY_APIS | 184838306 | 禁止變更任何 Display API 的行為。 |
ALWAYS_SANDBOX_DISPLAY_APIS | 185004937 | 強制應用程式中的 Display API 傳回應用程式邊界。Display API 會傳回邏輯顯示區域邊界,但有時候應用程式會假設 Display API 傳回應用程式邊界,這會導致 UI 問題。 |
|
OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS | 237531167 | 強制應用程式中的 View API 傳回應用程式邊界。View API 會傳回邏輯顯示區域邊界,但有時候應用程式會假設 View API 傳回應用程式邊界,這會導致 UI 問題。 |
|
相機相容性 | OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION | 263959004 | 關閉強制旋轉機制。根據預設,開啟相機預覽畫面時,系統會強制旋轉所有固定方向的相機應用程式。 |
OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH | 264304459 | 在系統強制旋轉相機預覽畫面時,移除所套用的預設強制重新整理機制。 | |
OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE | 264301586 | 在系統強制旋轉相機預覽畫面時,將強制重新整理切換為非強制重新整理,這有助在強制旋轉期間保留狀態。根據預設,Android 會在強制旋轉相機預覽畫面時,套用強制重新整理機制。強制重新整理機制可能會導致應用程式失去狀態或顯示黑色畫面,具體取決於應用程式快取先前狀態的方式。 | |
OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT | 250678880 | 裁剪內側前置鏡頭的影像緩衝區。如果停用此覆寫值,系統會移除內側前置鏡頭裁剪機制,並增加相機預覽畫面的視野。根據預設,某些摺疊式裝置 (請參閱參考裝置) 會在使用內側前置鏡頭時,裁剪所有相機應用程式的相機預覽畫面。 | |
其他 | OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS | 263259275 | 在分割畫面模式中,防止應用程式在失去焦點時顯示黑色畫面。應用程式會先等待焦點,再繪製應用程式內容,這可能導致應用程式凍結或顯示黑色畫面。此覆寫值可讓 Android 向應用程式傳送假焦點事件,通知應用程式再次開始繪製內容。 |
FORCE_RESIZE_APP
將套用覆寫值的套件強制設定為可調整大小。沒有 變更應用程式能否進入多視窗模式,但允許 應用程式調整大小時,不必進入大小相容性模式。
應用程式如何達成與覆寫值相同的結果
在應用程式資訊清單中,設定
android:resizeableActivity
屬性設為 true
,或針對
使用大小調整功能
android:resizeableActivity=false
,設定 android.supports_size_changes
傳送至 true
。
如何最佳化應用程式
使用回應式/自動調整式版面配置,讓應用程式根據各種螢幕大小自動調整 顯示比例。詳情請見 支援不同的螢幕大小。
如何停用或選擇不採用覆寫值
將屬性標記 PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES
設為
false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值,並讓應用程式可調整大小:
adb shell am compat enable FORCE_RESIZE_APP <package>
如何移除覆寫值:
adb shell am compat disable FORCE_RESIZE_APP <package>
注意:指令只能暫時套用或移除覆寫值。
FORCE_NON_RESIZE_APP
將要套用覆寫值的套件強制設定為無法調整大小,以及 在設定變更時進入大小相容性模式。
應用程式如何達成與覆寫值相同的結果
同時設定 android:resizeableActivity
屬性和
在應用程式資訊清單中,將 android.supports_size_changes
中繼資料標記設為 false
。
並宣告方向或顯示比例限制
如何最佳化應用程式
凡是在調整大小後順利運作的應用程式,都應具備
android:resizeableActivity
或android.supports_size_changes
已設為 true
。
其他應用程式則應改善調整大小後的運作情形。詳情請見
android:resizeableActivity。
如何停用或選擇不採用覆寫值
將屬性標記 PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES
設為
false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值,並將應用程式設為無法調整大小:
adb shell am compat enable FORCE_NON_RESIZE_APP <package>
如何移除覆寫值:
adb shell am compat disable FORCE_NON_RESIZE_APP <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO
為強制執行特定最小顯示比例的所有覆寫值把關。
應用程式如何達成與覆寫值相同的結果
在活動或應用程式層級設定 android:minAspectRatio
。
如何最佳化應用程式
請勿在應用程式中設定顯示比例限制。確認應用程式支援
不同的螢幕大小使用視窗大小類別
支援不同的版面配置,以配合應用程式
。請參閱 Compose WindowSizeClass
API
和 查看 WindowSizeClass
API。
如何停用或選擇不採用覆寫值
指定顯示比例限製或設定屬性標記
PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE
到 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
android:value="false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY
限制應用程式設定,強制針對活動指定最小顯示比例
的螢幕方向。預設為啟用,且只會生效
如果同時啟用 OVERRIDE_MIN_ASPECT_RATIO
。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何最佳化應用程式
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO_MEDIUM
將活動的最小顯示比例設為中等值 (3:2)
應用程式可如何達成與覆寫值相同的結果
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何最佳化應用程式
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO_LARGE
將活動的最小顯示比例設為較大值 (16:9)
應用程式可如何達成與覆寫值相同的結果
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何最佳化應用程式
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN
啟用分割畫面顯示比例。允許應用程式使用 顯示可用空間,避免加上黑邊。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何最佳化應用程式
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN
在直向全螢幕模式下停用最小顯示比例覆寫值,即可使用所有 可用的螢幕空間。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何最佳化應用程式
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_MIN_ASPECT_RATIO」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ANY_ORIENTATION
啟用下列覆寫值以覆寫任何方向:
- OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
- OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
- OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE
應用程式如何達成與覆寫值相同的結果
設定 activity:screenOrientation
資訊清單屬性。
或使用 Activity#setRequestedOrientation()
API。
如何最佳化應用程式
應用程式應支援所有方向。螢幕方向變更指的是
設定變更,操作方法有以下兩種:允許
請刪除並重新建立應用程式,或管理設定變更
你自己。如果您是自行管理設定變更,應用程式狀態可能會
使用 ViewModel
保留。在極少數情況下,您可以決定鎖定
只在小型螢幕上呈現方向,不過這麼做的縮放比例可能較低
讓使用者可以視需要旋轉應用程式在 Android 12L 以上版本中,
可以透過裝置設定覆寫固定方向。如要
如何處理設定變更
請參閱「處理設定變更」一文。
ViewModel 總覽,以及限制應用程式方向
而非大螢幕裝置。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ANY_ORIENTATION_TO_使用者
允許應用程式填滿可用的顯示空間。會覆寫任何方向、
應用程式資訊清單中指定的大小與顯示比例限制。其他
會忽略所有對
Activity#setRequestedOrientation()
。
應用程式如何達成與覆寫值相同的結果
請不要設定
android:screenOrientation
資訊清單 屬性,或將屬性設為"user"
。設定
android:resizeableActivity
資訊清單 屬性設為true
。在小螢幕上,在停用多視窗模式的情況下支援應用程式大小調整功能 模式搭配
android:resizeableActivity=false
運作,請將android.supports_size_changes
中繼資料標記至true
。「不要」設定minAspectRatio
和maxAspectRatio
。
如何最佳化應用程式
讓應用程式支援所有方向。不要設定 screenOrientation
。
會納入應用程式的資訊清單。支援應用程式大小調整功能
以及所有顯示比例,方法是將
android:resizeableActivity
屬性。true
。詳情請見
支援不同的螢幕大小。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ANY_ORIENTATION_TO_USER <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ANY_ORIENTATION_TO_USER <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
為套件中的所有活動啟用直向方向。除非 OVERRIDE_ANY_ORIENTATION 已啟用,覆寫值 只有在活動未指定其他固定方向時才能使用。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
啟用 nosensor 方向 套件。除非 OVERRIDE_ANY_ORIENTATION 為 啟用後,只有在沒有其他固定方向時,系統才會使用此覆寫值 由活動指定。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE
為 中的所有活動啟用 reverseLandscape 方向 檔案。除非 OVERRIDE_ANY_ORIENTATION 為 啟用後,只有在沒有其他固定方向時,系統才會使用此覆寫值 由活動指定。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA
限制 OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT、 OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR, 和 OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE 覆寫值只有在相機連線啟用時才會生效。
應用程式如何達成與覆寫值相同的結果
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來調整覆寫值的屬性標記
請參閱「OVERRIDE_ANY_ORIENTATION
」。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION
在顯示錯誤訊息時,將顯示方向限制為橫向自然方向 符合下列條件:
- 活動為全螢幕模式
- 選擇不採用元件屬性
未啟用「
PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE
」 - 已為以下裝置啟用裝置製造商忽略方向要求的設定: 螢幕
- 螢幕的自然方向為橫向
應用程式可如何達成與覆寫值相同的結果
不適用。應在應用程式邏輯中解決這項問題。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
啟用相容性政策,不根據應用程式方向更新應用程式方向
呼叫 Activity#setRequestedOrientation()
(當應用程式)
正重新啟動,或正在啟動相機相容性處理。
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION
敬上
至 true
。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
啟用相容性政策,忽略應用程式要求的螢幕方向
回覆應用程式呼叫
超過 Activity#setRequestedOrientation()
次
表示活動在固定方向上沒有上下黑邊。
應用程式如何達成與覆寫值相同的結果
不適用。應在應用程式邏輯中解決這項問題。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
到
false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED"
android:value="false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_RESPECT_REQUESTED_ORIENTATION
從可啟用的忽略方向要求行為中排除套件 由裝置製造商評估顯示區域或整個螢幕
應用程式如何達成與覆寫值相同的結果
不適用。應在應用程式邏輯中解決這項問題。
如何最佳化應用程式
請參閱「OVERRIDE_ANY_ORIENTATION
」。
如何停用或選擇不採用覆寫值
無法選擇不採用。如果應用程式不相容,停用此覆寫值可能會不安全 裝置由裝置製造商忽略方向要求 設定已啟用。與 Android 開發人員聯絡 關係來停用覆寫值。
用來調整覆寫值的屬性標記
此覆寫值沒有屬性標記。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>
注意:指令只能暫時套用或移除覆寫值。
NEVER_SANDBOX_DISPLAY_APIS
強制套件一律不套用 Display
API 沙箱機制
加上黑邊或大小相容性模式活動。Display
API
繼續提供顯示區域邊界。
應用程式如何達成與覆寫值相同的結果
透過
將 android:resizeableActivity
資訊清單屬性設為true
或 android.supports_size_changes
中繼資料標記至 true
。
如何最佳化應用程式
若是宣告為可徹底調整大小的應用程式,皆不應仰賴螢幕尺寸
放置 UI 元素請將應用程式遷移至符合以下條件的最新版 API
請提供 WindowMetrics
。如果您使用的是 Jetpack Compose,可以善用
WindowSizeClass
API,用於根據畫面數量繪製 UI
應用程式目前螢幕上的顯示區域詳情請見
視窗大小類別。
如何停用或選擇不採用覆寫值
無法選擇不採用。請停止使用已淘汰的 API。
用來調整覆寫值的屬性標記
此覆寫值沒有屬性標記。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable NEVER_SANDBOX_DISPLAY_APIS <package>
如何移除覆寫值:
adb shell am compat disable NEVER_SANDBOX_DISPLAY_APIS <package>
注意:指令只能暫時套用或移除覆寫值。
ALWAYS_SANDBOX_DISPLAY_APIS
強制套件一律套用 Display
API 沙箱機制
無論視窗模式為何Display
API 一律會提供應用程式邊界。
應用程式如何達成與覆寫值相同的結果
透過設定
android:resizeableActivity
屬性設為 false
,或
android.supports_size_changes
中繼資料標記至 false
。
如何最佳化應用程式
若是宣告為可徹底調整大小的應用程式,一律不應依賴螢幕尺寸
放置 UI 元素將應用程式從已淘汰的 API 遷移至
提供 WindowMetrics
的最新版 API詳情請見
WindowMetricsCalculator
。
如何停用或選擇不採用覆寫值
無法選擇不採用。請停止使用已淘汰的 API。
用來調整覆寫值的屬性標記
此覆寫值沒有屬性標記。
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable ALWAYS_SANDBOX_DISPLAY_APIS <package>
如何移除覆寫值:
adb shell am compat disable ALWAYS_SANDBOX_DISPLAY_APIS <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS
針對活動邊界,強制套件採用下列 View
API 的沙箱機制:
應用程式如何達成與覆寫值相同的結果
使用提供 應用程式視窗和相對於應用程式視窗 (而非 裝置螢幕和相對於裝置螢幕的偏移值。
如何最佳化應用程式
應用程式應使用 View
API,考量上下黑邊的可能性
以及應用程式套用的多視窗模式詳情請見
WindowMetricsCalculator
。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS"
android:value="false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION
停用強制旋轉機制。改善部分應用程式的使用者體驗。
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION
敬上
至 false
。
如何最佳化應用程式
請勿仰賴快取的相機感應器方向或裝置資訊。適用對象 相機相容性指引,請參閱 隆重推出相機觀景窗和支援 相機可調整大小的介面 應用程式。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION
敬上
至 true
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值,移除強制旋轉機制:
adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>
如何移除覆寫值,啟用強制旋轉機制:
adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH
停用強制旋轉後的活動重新整理機制。改善使用者體驗 重新整理作業導致應用程式狀態遺失的情形
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH
敬上
至 false
。
如何最佳化應用程式
詳情請見 OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH
敬上
至 true
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值,移除活動重新整理機制:
adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>
如何移除覆寫值,允許活動重新整理機制:
adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE
讓套用的套件使用 onResume()
重新整理活動
是 → onPause()
→ onResume()
週期,而非 onResume()
→
在相機相容性強制旋轉後,onStop()
→ onResume()
。
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE
敬上
至 true
。
如何最佳化應用程式
詳情請見 OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT
在直向模式下,強制將相機輸出內容裁剪為相反方向 相機方向與自然的裝置方向不符。多個應用程式 ,圖片也不會處理這種情況,而是顯示延展的影像。
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT
敬上
至 true
。
如何最佳化應用程式
詳情請見 OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION。
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT
敬上
至 false
。
用來調整覆寫值的屬性標記
<property android:name="android.camera.PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值,藉此套用內側前置鏡頭裁剪機制:
adb shell am compat enable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>
如何移除覆寫值,藉此移除內側前置鏡頭裁剪機制:
adb shell am compat disable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION
禁止應用程式停用應用程式分享螢幕畫面功能 (請參閱
媒體投影)。系統會在應用程式濫用
要強制執行的 createConfigForDefaultDisplay()
API
擷取全螢幕畫面並公開內容,危害使用者隱私
通知,這些是全螢幕,而非應用程式畫面
共用及所有應用程式。
應用程式如何達成與覆寫值相同的結果
允許預設媒體投影行為 (已在 Android 14 中實作,API
第 34 級,包含 createScreenCaptureIntent()
);
讓使用者決定要分享全螢幕或單一應用程式
都不會改變視窗大小或撥打
createScreenCaptureIntent(MediaProjectionConfig)
敬上
搭配 MediaProjectionConfig
呼叫 createConfigForUserChoice()
。
如何最佳化應用程式
允許使用者選擇要共用整個裝置螢幕或應用程式 視窗 (自 Android 14 起為預設行為)。
設定應用程式可調整大小 (resizeableActivity="true"
),
支援多視窗模式
如何停用或選擇不採用覆寫值
由於使用者隱私的重大,您的應用程式無法停用或退出計畫 。
用來調整覆寫值的屬性標記
無。
用來測試覆寫值的 ADB 指令
套用覆寫值,藉此取消應用程式停止分享部分螢幕畫面 (即啟用部分螢幕畫面分享功能):
adb shell am compat enable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>
移除覆寫值,讓應用程式停用部分畫面 分享:
adb shell am compat disable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>
注意:指令只能暫時套用或移除覆寫值。
OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS
啟用以下功能:在分割畫面模式下,針對未具有焦點的應用程式傳送假焦點。只有部分通知 等遊戲引擎取得焦點,再繪製應用程式內容。依此類推 假焦點可協助應用程式避免在未啟動的情況下顯示黑色畫面 目前還沒有焦點
應用程式如何達成與覆寫值相同的結果
設定屬性標記
PROPERTY_COMPAT_ENABLE_FAKE_FOCUS
到
true
。
如何最佳化應用程式
如果應用程式會處理多個方向和 我們只是想調整設定變更請遵循以下指示,讓應用程式適用大螢幕 「大型螢幕應用程式品質」規範。
如果您執行的是 Unity 遊戲引擎,請升級至 2019.4.40 以上版本
重新匯出遊戲。保留「Resizable Window
」選項
已在 Android 播放器中簽到
可以管理叢集設定,像是節點
資源調度、安全性和其他預先設定項目
如何停用或選擇不採用覆寫值
設定屬性標記
PROPERTY_COMPAT_ENABLE_FAKE_FOCUS
到
false
。
用來調整覆寫值的屬性標記
<property android:name="android.window.PROPERTY_COMPAT_ENABLE_FAKE_FOCUS"
android:value="true|false"/>
用來測試覆寫值的 ADB 指令
如何套用覆寫值:
adb shell am compat enable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>
如何移除覆寫值:
adb shell am compat disable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>
注意:指令只能暫時套用或移除覆寫值。
其他資源
- 「大型螢幕應用程式品質」規範
- 「核心應用程式品質」規範