裝置相容模式

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

裝置製造商可以透過個別應用程式覆寫值變更應用程式行為,來改善使用者體驗,及避免應用程式在特定裝置上當機。

參考裝置

下列裝置可能會因為應用程式不支援的異常設定或設定,而需要覆寫個別應用程式:

  • 平板電腦: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

最佳化

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

相容性暫時替代方案

為了維持連續性,如果在視窗中執行的應用程式採用固定方向或固定顯示比例,而不直接支援視窗的大小或方向,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 判定應用程式無法調整大小,就會叫用大小相容性模式。當活動移至與活動尺寸不相容的螢幕容器時,系統可能會重新調整應用程式大小,填滿裝置螢幕的至少一邊。

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

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

問題

大小相容性模式通常適用於具有螢幕方向或長寬比限制,且設為 (或遭系統判定為) 無法調整大小的活動。

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

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

最佳化

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

相容性暫時替代方案

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

閃爍迴圈

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

問題

在 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),並繼續無限迴圈。

最佳化

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

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

相容性暫時替代方案

在下列情況下,Android 會忽略對 Activity#setRequestedOrientation() 的呼叫:

相機預覽

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

問題

Android 相容性定義說明文件指出相機影像感應器的方向「必須經過調整,讓相機的長邊與螢幕的長邊對齊」。

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

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

最佳化

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

相容性暫時替代方案

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 會傳回應用程式的邊界,而非傳回裝置顯示區域的邊界。或開發人員誤用特殊用途的檢視 API,用來取得一般顯示指標。這會導致在應用程式視窗大小調整事件後,計算出錯誤的 UI 元素新位置,造成版面配置問題。

已淘汰且經常遭到濫用的 Display API:

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

遭到濫用的 View API:

最佳化

請勿依賴實體螢幕尺寸來決定 UI 元素位置。請根據 WindowMetrics 將應用程式遷移至 API,包括下列 WindowManager 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 活動邊界。

最佳化

位於工作活動堆疊中的透明活動,會繼承自身下方最頂層不透明活動的限制。在從活動建立到刪除,不透明活動的整個生命週期中,都必須提供不透明活動。因此,請勿從 Trampoline 活動啟動權限要求。

如果 Trampoline 活動啟動權限要求,使用者可能看不到權限對話方塊,因為在使用者有機會回應對話方塊之前,Trampoline 活動就會遭到刪除,而對話方塊活動的維度和位置可能不正確。

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

圓角

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

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

相容性暫時替代方案

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

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

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

Unity 遊戲

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

問題

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

最佳化

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

相容性暫時替代方案

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

測試應用程式相容性問題

如要測試應用程式,瞭解應用程式在不同板型規格上的行為,請善用下列資源:

已加上黑邊

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

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 提供的覆寫值會變更已設定的應用程式行為。舉例來說,即使應用程式資訊清單中已指定 resizeableActivity="false"FORCE_RESIZE_APP 覆寫值仍會指示系統略過大小相容性模式,並調整應用程式大小以符合顯示尺寸。

裝置製造商會在特定大螢幕裝置上,為特定應用程式 (或所有應用程式) 套用覆寫值。在 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.supports_size_changes 中繼資料標記設為 true,以便在 android:resizeableActivity=false 設為 false 且停用多視窗模式的情況下,支援大小調整功能。

如何最佳化應用程式

使用回應式/自動調整式版面配置,讓應用程式根據各種螢幕大小和顯示比例自動調整。請參閱「支援不同的螢幕大小」。

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

將屬性標記 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:resizeableActivityandroid.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 APIView 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

啟用下列覆寫值以覆寫任何方向:

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

設定 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。請「不要」設定 minAspectRatiomaxAspectRatio

如何最佳化應用程式

讓應用程式支援所有螢幕方向,請勿在應用程式資訊清單中設定 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_PORTRAITOVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOROVERRIDE_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

啟用相容性政策,在應用程式重新啟動或執行相機相容性處置時,略過應用程式方向的更新作業。

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

將屬性標記 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 的沙箱機制:

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

如要解決應用程式程式碼中的問題,您使用的 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 強制擷取全螢幕畫面並危害使用者隱私,會實作通知內容,這些內容擷取為全螢幕而非應用程式螢幕畫面分享,以及無論視窗模式為何,所有應用程式都會擷取。

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

允許預設媒體投影行為 (使用 createScreenCaptureIntent() 在 Android 14 中導入,API 級別 34 實作),讓使用者決定無論視窗模式為何,要分享全螢幕或單一應用程式視窗。或者,您也可以使用從呼叫 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 遊戲引擎,請升級至 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>

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

其他資源