裝置相容模式

對於宣告了螢幕方向和大小調整限制的應用程式，Android 會啟用相容性模式。這個模式可確保應用程式在大螢幕裝置和折疊式手機上運作順利，但會降低可用性。

裝置製造商、虛擬裝置擁有者¹和使用者可以透過個別應用程式覆寫值變更應用程式行為，改善應用程式版面配置，或避免應用程式在特定裝置上當機。

Android 16

Android 16 (API 級別 36) 會忽略螢幕方向、顯示比例和應用程式大小調整限制，改善最小寬度 >= 600 dp 的板型規格上應用程式的版面配置。

如果應用程式的目標 API 級別為 36，下列應用程式專屬覆寫值將無法運作：

• FORCE_RESIZE_APP
• FORCE_NON_RESIZE_APP
• OVERRIDE_MIN_ASPECT_RATIO
• OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY
• OVERRIDE_MIN_ASPECT_RATIO_MEDIUM
• OVERRIDE_MIN_ASPECT_RATIO_LARGE
• OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN
• OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN
• OVERRIDE_ANY_ORIENTATION
• OVERRIDE_ANY_ORIENTATION_TO_USER
• OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
• OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
• OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE
• OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA
• OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION
• OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
• OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
• OVERRIDE_RESPECT_REQUESTED_ORIENTATION
• OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS

選擇退出

您的應用程式可以指定 API 級別 36，但選擇不採用 Android 16 行為，在這種情況下，OVERRIDE_ANY_ORIENTATION_TO_USER 不適用。

宣告資訊清單屬性

如要停用 API 級別 36 的行為，請宣告 PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY 資訊清單屬性。

如要選擇不參與特定活動，請在 <activity> 元素中設定屬性：

<activity ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</activity>

如要為整個應用程式停用這項功能，請在 <application> 元素中設定屬性：

<application ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</application>

參考裝置

下列裝置可能需要針對每個應用程式進行覆寫，因為這些裝置的設定異常，或是應用程式不支援這些設定：

• 平板電腦：部分平板電腦 (例如 Pixel Tablet) 的自然方向為橫向。Display#getRotation() 傳回 Surface.ROTATION_0 時，表示裝置處於自然方向。如果應用程式假設 ROTATION_0 為直向，應用程式版面配置和相機預覽畫面可能會與裝置螢幕不符。
• 橫向折疊式裝置：部分折疊式裝置 (例如 Pixel Fold) 在折疊時為直向，展開時則為橫向。如果應用程式假設展開方向為直向，就可能發生閃爍迴圈或版面配置問題。
• 折疊式手機：展開的折疊式手機通常為直向。不過，摺疊手機通常會以橫向顯示小型螢幕。應用程式必須辨識並配合螢幕的不同方向。
• 外接螢幕：部分裝置可在外接螢幕上啟動桌面視窗工作階段。應用程式必須查詢外接螢幕的螢幕大小和解析度等資訊，否則可能會對螢幕做出錯誤的假設，導致應用程式行為不正確。
• 車輛螢幕：許多車輛螢幕都是橫向，但並非全部。開發車輛螢幕專用的停車應用程式，與開發平板電腦應用程式類似。

常見相容性問題

最常導致應用程式相容性問題的原因，包括應用程式方向限制、大小調整與顯示比例的限制、未正確處理相機預覽畫面方向，以及濫用 API。

黑邊

應用程式加上黑邊後，即可置中顯示在螢幕中央，或顯示在大螢幕的其中一側，方便使用者存取。應用程式的兩側、頂部和底部會加上襯邊，也就是上色的實心長條或模糊的桌布，來填滿未使用的顯示區域。

大螢幕裝置上經常出現黑邊，因為這類裝置的螢幕尺寸和顯示比例通常不同於標準手機，但大部分的應用程式都是為標準手機設計。

圖 1. 在橫向的平板電腦和摺疊式裝置上，僅限直向的應用程式會加上黑邊。

問題

應用程式具有固定的方向、固定的顯示比例，或是無法調整大小，因此不支援所有顯示設定。

以下設定可控制應用程式的方向和大小調整功能：

• screenOrientation：為應用程式指定固定的方向。應用程式也可以利用 Activity#setRequestedOrientation()，在執行階段設定方向。

• resizeableActivity：指出系統能否根據不同大小的視窗調整應用程式大小。在 Android 11 (API 級別 30) 以下版本中，這項設定可指定應用程式是否支援多視窗模式。在 Android 12 (API 級別 31) 以上版本中，則可指定應用程式能否在小型螢幕 (緊湊型視窗大小類別) 上支援多視窗模式。在 Android 12 以上版本中，無論這項設定為何，應用程式都可在大型螢幕 (中型或展開視窗大小類別) 上支援多視窗模式。

• maxAspectRatio：指定應用程式支援的最大顯示比例。只有 resizeableActivity 設為 false 的應用程式可設定 maxAspectRatio。

• minAspectRatio：指定應用程式支援的最小顯示比例。只有 resizeableActivity 設為 false 的應用程式可設定 minAspectRatio。

cancel

在橫向裝置上難以使用的僅限直向應用程式。

最佳化

應用程式應支援所有裝置和多視窗模式的顯示方向和大小。請從應用程式版面配置和資訊清單檔案中，移除所有方向和固定顯示比例的限制。

check_circle

應用程式支援所有裝置方向。

相容性暫時替代方案

如果在視窗中執行的應用程式採用固定方向或固定顯示比例，而不直接支援視窗的大小或方向，Android 就會為應用程式加上黑邊，以維持連續性。

從 Android 12 (API 級別 31) 到 12L (API 級別 32)，Android 平台會為加上黑邊的應用程式套用各種改善項目。裝置製造商會實作這些 UI 改善項目。您不需要進行額外的開發作業，應用程式即可獲得改善。

Android 12 (API 級別 31) 推出了以下外觀改善項目，皆可由裝置製造商設定：

• 圓角：讓應用程式視窗的四個角更圓滑。
• 系統資訊列透明度：疊加在應用程式上的狀態和導覽列皆為半透明，讓列上的圖示在黑邊背景中一律清晰可見。
• 可設定的顯示比例：您可以調整應用程式的顯示比例，改善應用程式的外觀。

圖 2. 加上黑邊且 UI 經過改善的應用程式。

Android 12L (API 級別 32) 新增了下列功能改善項目：

• 可設定的位置：如果裝置螢幕較大，裝置製造商可將應用程式放在螢幕的左側或右側，方便使用者操作應用程式。

• 經過重新設計的重新啟動按鈕：裝置製造商可為大小相容性模式的重新啟動按鈕賦予新外觀，方便使用者看到按鈕。

Android 13 (API 級別 33) 為使用者新增了說明對話方塊，介紹如何在畫面上為加上黑邊的應用程式調整位置，或是在分割畫面模式中加上黑邊：

圖 3. 加上黑邊的應用程式顯示使用者說明對話方塊。

大小相容性模式

大小相容性模式是黑邊效果，可維持應用程式的顯示比例，並包含重新啟動控制項。這個控制項可讓使用者重新啟動應用程式，並重新繪製顯示畫面。如果 Android 判定應用程式無法調整大小，就會叫用大小相容性模式。如果活動移至與活動尺寸不相容的螢幕容器，系統可能會重新調整應用程式大小，填滿裝置螢幕的至少一邊。

可觸發大小相容性模式的裝置設定包括：

• 裝置旋轉
• 摺疊式裝置摺疊或展開
• 切換全螢幕和分割畫面顯示模式

問題

會套用大小相容性模式的活動一般具有方向限制或顯示比例限制，且設為 (或遭系統判定為) 無法調整大小。

如果應用程式符合下列任一條件，就視為可調整大小，不會進入大小相容性模式：

• 能使用 resizeableActivity="true" 調整大小
• 支援子母畫面 (PIP) 模式
• 已嵌入
• 具備由裝置製造商套用的 FORCE_RESIZE_APP 個別應用程式覆寫值 (系統會忽略應用程式所設定的屬性)

如果應用程式「不」符合任一條件，就視為無法調整大小，可能會進入大小相容性模式。

cancel

在多視窗模式下，無法調整大小的應用程式異常終止。

最佳化

應用程式應支援所有顯示大小。如要啟用應用程式的大小調整功能，請在應用程式資訊清單中，將 <activity> 或 <application> 元素的 android:resizeableActivity 屬性設為 true。請為應用程式設計回應式/自動調整式版面配置。詳情請參閱「支援不同的螢幕大小」和「支援多視窗模式」。

check_circle

應用程式適用於所有視窗大小。

相容性暫時替代方案

如果系統判定可將應用程式大小重新調整為填滿裝置視窗的至少一邊，進而改善應用程式加上黑邊後的呈現效果，應用程式就會進入大小相容性模式。系統會顯示重新啟動控制項，用來重新建立應用程式程序，進而重新建立活動並重新繪製顯示畫面。請參閱「程序和執行緒總覽」。

warning

在橫向模式下，僅限直向的應用程式會加上黑邊，並由重新啟動控制項調整大小。

顯示相容模式

顯示器相容性模式可防止應用程式在不同螢幕之間移動時重新啟動，因為這可能會觸發設定變更，例如色彩模式、觸控螢幕可用性或螢幕密度變更。

系統預設會為遊戲啟用顯示相容性模式 (根據 android:appCategory 標記)，以提升穩定性和連續性。與大小相容性模式不同，顯示器相容性模式不會凍結應用程式的設定。應用程式仍可透過 onConfigurationChanged() 回呼等 API 接收所有設定更新，但可避免重新啟動造成中斷。也就是說，即使遊戲處於螢幕相容模式，只要正確支援 onConfigurationChanged() 等 API，仍可即時更新 UI。

如要停用螢幕相容模式並在應用程式中處理設定變更，請在應用程式的 AndroidManifest.xml 檔案中宣告支援設定變更，並在 onConfigurationChanged() 回呼中處理設定變更。

<activity
    android:name=".MyGameActivity"
    android:configChanges="colorMode|touchscreen|density|...">
    ...
</activity>

閃爍迴圈

如果應用程式不支援所有顯示方向，就可能會在設定變更時重複要求新的方向，導致建立無限迴圈，讓螢幕畫面不停閃爍或旋轉。

問題

在 Android 12 (API 級別 31) 以上版本中，裝置製造商可將裝置設定為忽略應用程式指定的方向限制，並強制執行相容性模式。舉例來說，當活動顯示在摺疊式裝置的橫向平板電腦大小內螢幕時，裝置可能會忽略活動的 android:screenOrientation="portrait" 設定。

如果系統忽略應用程式的方向限制，應用程式可以呼叫 Activity#setRequestedOrientation()，以程式輔助方式設定方向。如果應用程式未處理設定變更，這個呼叫會觸發應用程式的重新啟動作業。詳情請參閱「處理設定變更」。重新啟動後，系統會再次忽略應用程式的螢幕方向限制，應用程式就會重複呼叫 setRequestedOrientation()，而呼叫會觸發應用程式的重新啟動作業，因此形成自我循環的迴圈。

另一個可能發生此問題的情況，則是裝置螢幕的自然方向為橫向。自然方向是指 Android 判定的「一般」螢幕方向，若為橫向，則呼叫 Display#getRotation() 時會傳回 Surface.ROTATION_0，而裝置採用的是橫向顯示比例。過去應用程式假設 Display.getRotation() = Surface.ROTATION_0 表示裝置為直向，但其實不一定，例如在某些摺疊式裝置的內螢幕和某些平板電腦上就並非直向。

在摺疊式裝置的內螢幕上，橫向的應用程式可能會檢查螢幕旋轉情形、接收 ROTATION_0 的值、假設裝置的自然方向為直向，並呼叫 setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) 重新設定應用程式版面配置。當橫向的應用程式重新啟動後，可能會再次檢查螢幕旋轉情形、接收 ROTATION_0 的值、呼叫 setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) 等等，形成無限迴圈。

cancel

在直向螢幕上，僅限橫向的應用程式會重複呼叫 Activity#setRequestedOrientation()。

最佳化

應用程式「不得」執行下列操作：

• 在活動 onCreate() 方法中使用 Activity#setRequestedOrientation() 設定預設方向，因為未處理的設定變更可能會意外觸發方向要求
• 假設裝置的自然方向 (ROTATION_0) 為直向
• 請根據與目前視窗大小無關的信號設定方向，例如 Display#getRotation()、是否出現 FoldingFeature，或是已淘汰的 API。

check_circle

應用程式會處理設定變更，且沒有方向限制，因此不會進入閃爍迴圈。

相容性暫時替代方案

在下列情況中，Android 會忽略對 Activity#setRequestedOrientation() 的呼叫：

• 系統已透過先前呼叫的方法重新啟動活動，或是已啟用相機相容性的強制旋轉處置 (詳情請參閱下方「相機預覽」一節)。

  裝置製造商可利用 OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION，將這項行為套用至應用程式。

• 活動在一秒內發出超過兩個方向要求，表示已發生迴圈。Android 從迴圈中選擇要求時，會使用可將應用程式顯示區域最大化的要求。

  裝置製造商可利用 OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED，將這項行為套用至應用程式。

• 虛擬裝置擁有者已在特定裝置上覆寫方法呼叫。

相機預覽

在平板電腦、筆記型電腦和摺疊式裝置螢幕上，相機應用程式的相機預覽畫面 (或觀景窗) 可能會沒有對齊或變形。

問題

Android 相容性定義說明文件規定，相機圖片感應器的方向「必須經過調整，讓相機的長邊對齊螢幕的長邊」。

應用程式通常會假設裝置方向和相機感應器方向皆為直向，這在標準手機上是合理假設，但對於平板電腦、筆記型電腦和這類電腦的相機感應器而言，自然方向可能是橫向。此外，摺疊式裝置等新板型規格可具有多個自然方向，且多個相機感應器的方向皆不同。

如果使用應用程式未預期的相機方向啟動活動，或切換不同的相機或裝置螢幕 (適用於摺疊式裝置)，可能會導致相機預覽畫面未對齊或變形。

cancel

大螢幕摺疊式裝置上未對齊和變形的相機預覽畫面。

最佳化

相機應用程式必須正確辨別及管理裝置方向和相機感應器方向，才能正確對齊及縮放相機預覽畫面。應用程式必須計算裝置旋轉情形、感應器旋轉情形，以及螢幕或視窗顯示比例，然後將計算結果套用至相機預覽畫面。如需詳細指南，請參閱「相機預覽」和「CameraViewfinder 介紹」。

check_circle

在所有裝置方向上，相機預覽畫面皆正確對齊及縮放。

相容性暫時替代方案

Display#getRotation() 傳回 Surface.ROTATION_0 時，表示裝置處於自然方向。系統會根據裝置的自然方向計算 CameraCharacteristics.SENSOR_ORIENTATION。針對僅限直向的應用程式，Android 會根據裝置的自然方向對齊直向視窗，這也是大多數應用程式預期的情況。此外，當感應器方向為橫向，且相機預覽畫面為直向時，Android 會裁剪相機感應器的影像。具體解決方法如下：

• 為僅限直向的應用程式強制旋轉相機預覽畫面：如果應用程式僅限直向，就會預期裝置的自然方向和相機感應器方向皆為直向。但在 Android 12 (API 級別 31) 以上版本中，如果裝置製造商忽略方向規格，應用程式就能在多個裝置方向中執行。

  當僅限直向的應用程式連上相機時，Android 會強制旋轉應用程式，將應用程式的直向視窗對齊裝置的自然方向。

  在部分平板電腦 (請參閱參考裝置) 上，應用程式直向視窗會旋轉為全螢幕直向視窗，對齊裝置的自然方向。強制旋轉後，應用程式就會占據整個螢幕畫面。

  

  warning

  平板電腦 - 經過強制旋轉的僅限直向應用程式。

  在可摺疊裝置的橫向內螢幕上 (請參閱參考裝置)，僅限直向的活動會旋轉為橫向，對齊裝置未摺疊時的自然方向。強制旋轉後，應用程式會加上黑邊。

  

  warning

  摺疊式裝置 - 經過強制旋轉的僅限直向應用程式，且已加上黑邊。

• 內側前置鏡頭裁剪：部分摺疊裝置的內側前置鏡頭感應器為橫向。除了在摺疊式裝置的內螢幕上強制旋轉相機預覽畫面外，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：

• getMetrics()
• getSize()
• getRealMetrics()
• getRealSize()
• getRectSize()
• getWidth()
• getHeight()

詳情請參閱「支援多視窗模式」。

遭到濫用的 View API：

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

cancel

已淘汰的 API 錯誤計算應用程式邊界，導致應用程式內容未顯示在畫面上。

最佳化

請勿依賴實體螢幕尺寸來決定 UI 元素位置。請根據 WindowMetrics 將應用程式遷移至 API，包括下列 WindowManager API：

• 平台：

  • getCurrentWindowMetrics()
  • getMaximumWindowMetrics()

• Jetpack：

  • WindowMetricsCalculator#computeCurrentWindowMetrics()

  • WindowMetricsCalculator#computeMaximumWindowMetrics()

check_circle

API 正確計算應用程式視窗指標。

相容性暫時替代方案

以下兩項覆寫值會調整已淘汰的 Display API 和遭到濫用的 View API，傳回應用程式邊界：ALWAYS_SANDBOX_DISPLAY_APIS 適用於 Display 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 活動邊界。

cancel

活動是透過 Trampoline 啟動，因此對話方塊的位置有誤。

最佳化

位於工作活動堆疊中的透明活動，會繼承自身下方最頂層不透明活動的限制。在透明活動的整個生命週期，也就是從活動建立到刪除的過程中，不透明活動都應可供使用。因此，請勿從 Trampoline 活動啟動權限要求。

若是由 Trampoline 活動啟動權限要求，使用者可能會看不到權限對話方塊，因為在使用者有機會回應對話方塊之前，Trampoline 活動就會遭到刪除，且對話方塊活動的尺寸和位置可能計算有誤。

應用程式用來啟動權限要求的活動應一律顯示在畫面上，直到使用者做出權限決定。

圓角

活動可能是透明的，原因在於指定背景透明度的樣式，或是活動內容未填滿可用的顯示空間。如果透明活動填滿可用的顯示空間，當裝置製造商為活動設定了圓角，系統就會自動將圓角套用至活動。但如果透明活動 (例如權限對話方塊) 未填滿可用空間，您可以自行決定是否要套用圓角。

對話方塊版面配置通常會使用 LayoutParams.WRAP_CONTENT，而不是 LayoutParams.MATCH_PARENT，因此權限對話方塊不會填滿可用的顯示空間。

check_circle

圓角的對話方塊正確疊加在可見的啟動活動上。

相容性暫時替代方案

請持續顯示啟動對話方塊活動，直到使用者回應對話方塊。

系統會確保活動堆疊中的透明活動從自身下方第一個不透明活動繼承所有限制，包括與以下項目相關的限制：

• 大小相容性模式
• 方向
• 顯示比例

Unity 遊戲

Unity 遊戲會在 Android 全螢幕或多視窗模式下執行。不過，當應用程式進入多視窗模式時，許多 Unity 遊戲都會失去焦點，並停止繪製內容。

問題

Unity 在 Unity 2019.4 中新增了 Resizable Window 選項，支援 Android 多視窗模式。不過，初始實作項目無法正確回應多視窗模式下的活動生命週期，因此當應用程式失去焦點時，UnityPlayer 會暫停執行作業，並顯示黑色畫面或遊戲的最後一個凍結影格。只有在使用者輕觸螢幕後，遊戲才會繼續執行。許多使用 Unity 引擎的應用程式都面臨這個問題，且會在多視窗模式下顯示為黑色視窗。

cancel

遊戲在多視窗模式下失去焦點，顯示為黑色視窗。

最佳化

請將 Unity 升級至 2019.4.40 以上版本，然後重新匯出遊戲。請保持勾選 Android Player 設定中的 Resizable Window 選項，否則即使遊戲會在多視窗模式下完整顯示，也仍會在失去焦點時暫停。

check_circle

即使未處於焦點，遊戲也能在多視窗模式下正確顯示內容。

相容性暫時替代方案

裝置製造商可以套用 OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS 個別應用程式覆寫值，在多視窗模式下為應用程式提供假焦點事件。此覆寫值可讓活動重新繪製內容，而不會顯示黑色畫面。

電腦分割視窗

應用程式在電腦視窗環境中執行時，可能會遇到其他相容模式。

鎖定螢幕方向的應用程式可自由調整大小，即使活動鎖定為直向，使用者仍可將應用程式大小調整為橫向。

check_circle

即使應用程式鎖定螢幕方向，仍可自由調整大小。

不過，如果活動宣告為不可調整大小 (resizeableActivity = false)，活動 UI 會縮放，但維持相同比例。

check_circle

系統會縮放宣告為無法調整大小的活動 UI。

在電腦視窗中預覽攝影機畫面

當桌面視窗模式下的應用程式啟動相機預覽時，觀景窗的 UI 會縮放，但仍維持原始長寬比。應用程式視窗的其餘部分可以自由調整大小。

check_circle

調整含有攝影機觀景窗的視窗大小

測試應用程式相容性問題

如要測試應用程式，瞭解應用程式在不同板型規格上的行為，請參考下列資源：

• 裝置串流：如要在由 Google 資料中心代管的正式生產裝置 (包括參考裝置) 上測試應用程式，請參閱「Firebase 支援的 Android 裝置串流 」
• Android Studio 中的模擬器：如要瞭解如何為參考裝置建立模擬器，請參閱「建立及管理虛擬裝置」
• Android Studio 大小調整模擬器：如要瞭解如何存取虛擬裝置，請參閱「在 Android Emulator 上執行應用程式」

已加上黑邊

請確認每個活動都能使用應用程式可用的所有顯示空間。首先，請在測試資料夾中宣告下列程式碼：

fun isLetterboxed(activity: AppCompatActivity): 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()
    }
}
DeviceCompatibilityModeKotlinSnippets.kt

public boolean isLetterboxed(AppCompatActivity 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();
}
DeviceCompatibilityModeJavaSnippets.java

接著執行測試，藉此宣告行為，並確保目標活動未加上黑邊：

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertFalse(it.isLetterboxed())
    }
}
DeviceCompatibilityModeTestKotlinSnippets.kt

@Rule
public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class);

@Test
public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario =
        ActivityScenario.launch(MainActivity.class)) {
            scenario.onActivity( activity -> {
                assertFalse(activity.isLetterboxed());
            });
        }
}
DeviceCompatibilityModeTestJavaSnippets.java

在理想情況下，請只執行這種測試，直到測試傳遞並宣告應用程式活動占滿應用程式可用的整個顯示空間。請在所有裝置類型上測試應用程式，確保行為一致。

個別應用程式覆寫值

Android 提供的覆寫值可能會變更已設定的應用程式行為。舉例來說，即使應用程式資訊清單中已指定 resizeableActivity="false"，FORCE_RESIZE_APP 覆寫值仍會指示系統略過大小相容性模式，並調整應用程式大小以符合螢幕尺寸。

裝置製造商會在特定的大螢幕裝置上，對選取的應用程式或所有應用程式套用覆寫值。在 Android 14 (API 級別 34) 以上版本中，使用者可以透過裝置設定套用應用程式的覆寫設定。在 Android 16 (API 級別 36) 以上版本中，虛擬裝置擁有者可對所管理的特定裝置套用覆寫。

使用者個別應用程式覆寫值

在 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 不會產生任何影響。

為所有螢幕最佳化應用程式：請勿在應用程式中設定顯示比例限制。使用視窗大小類別，根據可用顯示空間大小支援不同的版面配置。

裝置個別應用程式覆寫值

裝置製造商和虛擬裝置擁有者 (選取受信任和具備特殊權限的應用程式) 會在特定裝置 (包括平板電腦、摺疊式裝置、ChromeOS 裝置和車用螢幕) 上，針對個別應用程式套用覆寫。根據預設，參考裝置可能會為多種應用程式套用部分覆寫值。

應用程式可選擇不採用大部分覆寫值 (見下方的「個別應用程式覆寫值」表格)。

您可以使用相容性架構，在啟用或停用覆寫值的情況下測試應用程式。詳情請參閱「相容性架構工具」。覆寫值一旦啟用，就會套用至整個應用程式。

您也可以使用 Android Debug Bridge (ADB) 啟用或停用覆寫值，並判斷應用程式適用哪些覆寫值。

請按照以下說明啟用或停用覆寫值：

adb shell am compat enable/disable <override name/id> <package>

如果是參考裝置，請確認應用程式適用哪些覆寫值：

adb shell dumpsys platform_compat | grep <package name>

下表列出可用的覆寫值，並說明如何最佳化應用程式，讓應用程式不需仰賴覆寫值。您可以在應用程式資訊清單中新增屬性標記，選擇不採用部分覆寫值。

FORCE_RESIZE_APP

將套用覆寫值的套件強制設定為可調整大小，並可進入多視窗模式。適用於所有螢幕尺寸。

應用程式如何達成與覆寫值相同的結果

在應用程式資訊清單中，將 android:resizeableActivity 屬性設為 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 和 View 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_SMALL

將活動的最小顯示比例設為較小值 (4:3)。

應用程式如何達成與覆寫值相同的結果

請參閱「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_SMALL <package>

如何移除覆寫值：

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <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_USER

讓應用程式填滿可用的螢幕空間。覆寫應用程式資訊清單中指定的任何方向、大小調整和顯示比例限制。此外，也會忽略對 Activity#setRequestedOrientation() 或 Activity#getRequestedOrientation() 的任何呼叫。

應用程式如何達成與覆寫值相同的結果

• 請勿設定 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 元素的位置。請將應用程式遷移至提供 WindowMetrics 的最新版 API。使用 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 的沙箱機制：

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

應用程式如何達成與覆寫值相同的結果

如要解決應用程式程式碼中的問題，您使用的 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() 實作)，讓使用者無論視窗模式為何，都能決定要分享全螢幕畫面或單一應用程式視窗。或者，使用從 createConfigForUserChoice() 呼叫傳回的 MediaProjectionConfig 引數呼叫 createScreenCaptureIntent(MediaProjectionConfig)。

如何最佳化應用程式

允許使用者在媒體投影期間，選擇要分享整個裝置螢幕畫面還是應用程式視窗。這項設定是 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 遊戲引擎，請升級至 Unity 2019.4.40 以上版本，並重新匯出遊戲。請保持勾選 Android Player 設定中的「Resizable Window」選項。

如何停用或選擇不採用覆寫值

將屬性標記 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>

注意：指令只能暫時套用或移除覆寫值。

OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS

啟用覆寫功能後，活動會收到設定，以及說明文字列插邊。通常，說明文字列插邊會與設定分離。

應用程式如何達成與覆寫值相同的結果

啟用無邊框螢幕顯示，或將應用程式的目標 SDK 更新至 API 級別 35 以上。請參閱以下資訊：

• Compose：視窗插邊簡介
• 檢視畫面：在檢視畫面中以無邊框方式顯示內容
• 設定：行為變更：指定 Android 15 以上版本的應用程式

如何最佳化應用程式

如果應用程式啟用無邊框顯示，或指定 API 級別 35 以上版本為目標，即可避免這個問題。

如何停用或選擇不採用覆寫值

啟用無邊框顯示，或指定 API 級別 35 以上版本為目標。

用來調整覆寫值的屬性標記

無。

用來測試覆寫值的 ADB 指令

如何套用覆寫值：

adb shell am compat enable OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS <package>

如何移除覆寫值：

adb shell am compat disable OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS <package>

注意：指令只能暫時套用或移除覆寫值。

其他資源

• 「大型螢幕應用程式品質」規範
• 「核心應用程式品質」規範