大螢幕應用程式相容性設定指南

本頁提供完整的設定指南和索引，說明如何設定 Android 大螢幕應用程式相容性設定疊加層。

螢幕

本節列出所有會影響顯示層級設定的設定。

名稱 位置 類型 預設
ignoreOrientationRequest display_settings.xml config false
true 適用於大螢幕 (>= 600dp)
說明
讓使用者在指定螢幕上，免費旋轉固定方向的活動。
範例： 
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>

使用情境或背景資訊
螢幕會忽略所有應用程式要求的螢幕方向，並加上黑邊。
適用於所有大螢幕裝置和 Android Automotive OS。搭載 Android 16 以上版本的大螢幕裝置，預設會採用這種模式。smallestScreenWidthDp >= 600dp
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
針對沉浸式應用程式啟用螢幕旋轉相容性政策，避免在全螢幕模式下自動旋轉為非最佳螢幕方向。這是必要步驟，因為遊戲等沉浸式應用程式通常不會針對所有螢幕方向進行最佳化，旋轉螢幕時可能導致使用者體驗不佳。此外，部分遊戲會使用感應器來進行遊戲，因此使用者開啟自動旋轉功能時，可能會意外觸發這類旋轉。
只有在啟用 ignoreOrientationRequest 時才適用。

用途或情境
鎖定沉浸式應用程式的螢幕旋轉功能。

顯示比例

本節列出所有會影響活動層級視窗長寬比設定的設定。

名稱 位置 類型 預設
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
說明
設定固定螢幕方向的上下黑邊顯示比例。系統會忽略小於或等於 1.0 的值。

用途或情境
設定裝置預設顯示比例，適用於大多數有上下黑邊的應用程式。通常會接近正方形顯示比例。
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要將分割畫面長寬比設為無法調整大小的應用程式的預設長寬比。

用途或情境
大多數無法調整大小的應用程式都預期採用直向糖果條手機版面配置。
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要將螢幕顯示比例設為所有上下留黑邊應用程式的預設顯示比例。

用途或情境
設定以程式輔助方式使用螢幕顯示比例，而非設定浮點值。

相機

本節列出所有設定，這些設定會在 onCameraOpened 回呼時影響應用程式。這些設定可能會影響螢幕顯示、活動和攝影機設定。

名稱 位置 類型 預設
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
針對相機緩衝區與應用程式視窗之間的方向不符所導致的問題，啟用相機相容性處理程序。
這包括強制旋轉與全螢幕相機連線的固定方向活動，以及在分割畫面中顯示工具提示。
強制旋轉處置可透過個別應用程式覆寫值停用： OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION。

用途或情境
透過強制旋轉螢幕，使螢幕方向與應用程式要求的方向一致，修正旋轉的相機預覽畫面。
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定活動是否在啟用相機相容性處置，且活動以全螢幕模式連線至相機時，使用分割畫面長寬比。

用途或情境
將活動加上上下黑邊，使長寬比類似於長條形，修正相機預覽畫面遭到拉伸的問題。
通常會與橫向裝置上已啟用的強制旋轉處理方式 (config_isWindowManagerCameraCompatTreatmentEnabled 和 camera.enable_landscape_to_portrait) 一起使用，模擬活動的直向長條狀長寬比，修正攝影機相容性問題。
camera.enable_landscape_to_portrait 系統屬性 Bool false
說明
：閘道會限制處理方式。OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT
在自然方向為橫向的相機上，強制裁剪相機輸出內容並旋轉 90 度，模擬自然方向為直向。裝置上所有橫向攝影機回報的攝影機感應器方向皆為直向。許多應用程式都不會處理這種情況，且會顯示延展的影像。

用途或情境
啟用相機 HAL 旋轉和裁剪處理。如要進一步瞭解處理方式，請參閱「旋轉、裁剪、縮放」。
在建構時，將下列內容新增至 mk 檔案：PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
這項處理方式需要裝置支援 SCALER_ROTATE_AND_CROP HAL。請參閱「CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES」。
如需 SCALER_ROTATE_AND_CROP 的 HAL 專屬實作指引，請參閱 metadata_definitions.xml。

背景和使用者介面

本節列出套用至 UI 自訂項目的上下黑邊層表面，或活動層級的所有設定。

名稱 位置 類型 預設
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
說明
設定以上下黑邊模式顯示活動時的圓角半徑。如果值小於 0，系統會啟用圓角，半徑等於裝置底部圓角半徑的最小值。預設值 0 會在 AppCompatLetterboxPolicy 中關閉圓角邏輯。

用途或情境
通常會設定為與實體裝置的圓角相符。
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否啟用半透明活動的上下黑邊特定行為。

用途或情境
啟用半透明活動或模式的上下黑邊，並限制在上下黑邊活動設定內。這項政策適用於 TransparentPolicy。
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否啟用傳送相容性虛擬焦點，以供分割畫面恢復活動使用。
這是必要步驟，因為有些遊戲引擎會等到取得焦點後，才繪製應用程式內容，而多視窗模式預設不會提供焦點。

用途或情境
舊版標記，可對 Unity 遊戲引擎套用相容性處理方式，適用於進入分割畫面模式後變成黑色，且只會在使用者輕觸並聚焦應用程式後繪製的應用程式。
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
說明
設定上下黑邊背景的角落外觀：
  • 0 - 使用 R.color.config_letterboxBackgroundColor 中指定的顏色做為實心背景。
  • 1 - 針對有黑邊的應用程式，在 R.attr.colorBackground 中指定的顏色。
  • 2 - 為有上下黑邊的應用程式在 R.attr.colorBackgroundFloating 中指定的顏色。
  • 3 - 模糊或深色半透明的桌布。下列至少一個參數必須大於 0：config_letterboxBackgroundWallpaperBlurRadius或 config_letterboxBackgroundWallpaperDarkScrimAlpha。如果不是這種情況，或是提供模糊半徑，但裝置不支援模糊效果，且選取這個選項，則實作方式會預設為選項 0。如果指定的值超出這個範圍，系統會假設為選項 0。


用途或情境
由於現有效能問題，這項功能尚未推出。原始設備製造商 (OEM) 可以自行實作這項功能，但 Android 開放原始碼計畫 (AOSP) 不會處理任何錯誤。
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
說明
如果符合下列任一條件，系統會設定上下黑邊的背景顏色： true：

  • 已為「R.integer.config_letterboxBackgroundType」選取「0」選項。
  • 已為 R.integer.config_letterboxBackgroundType 選取 1 選項，但未為應用程式指定 R.attr.colorBackground。
  • 已為 R.integer.config_letterboxBackgroundType 選取 2 選項，但未為應用程式指定 R.attr.colorBackgroundFloating。
  • 為 R.integer.config_letterboxBackgroundType 選取選項 3， 並要求模糊處理，但裝置不支援這項功能，或未提供深色半透明 阿爾法和模糊半徑。


用途或情境
由於現有效能問題，這項功能尚未推出。原始設備製造商 (OEM) 可以自行實作這項功能，但 Android 開放原始碼計畫 (AOSP) 不會處理任何錯誤。
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
說明
設定 R.integer.config_letterboxBackgroundType 中選項 3 的模糊半徑。系統會忽略小於 0 的值，並使用 0。

用途或情境
由於現有效能問題，這項功能尚未推出。原始設備製造商 (OEM) 可以自行實作這項功能，但 Android 開放原始碼計畫 (AOSP) 不會處理任何錯誤。
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
說明
設定在選取「Option 3」做為 R.integer.config_letterboxBackgroundType 時，顯示在桌布信箱模式背景上的半透明黑色遮罩的 Alpha 值。系統會忽略小於 0 或大於或等於 1 的值，並改用 0.0 (透明)。

用途或情境
由於現有的效能問題，這項功能尚未推出。原始設備製造商 (OEM) 可以自行實作這項功能，但 Android 開放原始碼計畫 (AOSP) 不會處理任何錯誤。

可連線性和定位

本節列出套用至活動層級視窗設定的所有設定，方便您進行無障礙設定。

名稱 位置 類型 預設
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要在全螢幕視窗模式下，為加上黑邊的應用程式啟用水平可及性重新定位功能。

用途或情境
將直向應用程式重新定位至左側或右側，方便存取。
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
說明
設定無邊框應用程式視窗中心的水平位置。
0 對應螢幕左側，1 則對應右側。
如果指定值小於 0 或大於 1，系統會忽略該值。如果不是書本模式，則會使用中央位置 (0.5)。如果是書本姿勢，系統會使用左側位置 (0.0)。

用途或情境
如果是直向上下留黑邊的應用程式，預設會置中。
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要在全螢幕視窗模式中，為有上下黑邊的應用程式啟用垂直可及性重新定位功能。

用途或情境
將橫向應用程式重新定位至頂端或底部，方便存取。
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
說明
設定無邊框應用程式視窗中心的垂直位置。
值 0 對應螢幕上方，1 則對應下方。
如果指定值小於 0 或大於 1，系統會忽略該值。如果不是免手持模式，系統會使用中央位置 (0.5)。如果是桌上型電腦模式，則會使用頂端位置 (0.0)。

用途或情境
在大螢幕裝置上設定為置中，適用於橫向黑邊應用程式。
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要在全螢幕視窗模式下，為加上黑邊的應用程式啟用書本模式自動橫向可及性定位。

用途或情境
讓加上黑邊的直向應用程式在摺疊式裝置處於書本模式時，在左右兩側之間移動。
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
說明
設定應用程式加上黑邊時，視窗中心點的水平位置 (處於書本模式)。
0 對應螢幕左側，1 則對應右側。 如果指定的值小於 0 或大於 1，系統會忽略該值並使用左側位置 (0.0)。

用途或情境
應用程式在書本模式中重新定位時，位置移動的乘數。
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
說明
啟用單手操作模式後，如果應用程式在橫向裝置方向和書本模式下處於全螢幕狀態，系統會設定加上黑邊的應用程式視窗預設水平位置。啟用單手模式後，位置可以變更為左側、中間和右側：
  • 選項 0 - 左
  • 選項 1 - 中心
  • 選項 2 - 右側
如果指定的值超出這個範圍，系統會假設為選項 0 (左)。

用途或情境
應用程式在書籍模式中的預設位置。
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
說明
：設定應用程式視窗在桌上型電腦模式下，出現黑邊時的垂直位置。
值 0 對應螢幕上方，1 則對應下方。如果指定值小於 0 或大於 1，系統會忽略該值並使用頂端位置 0.0。

用途或情境
應用程式在桌上型電腦模式下，於摺疊式裝置中移動位置的乘數。
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
說明
設定應用程式視窗加上黑邊時的預設垂直位置。啟用單手模式後，如果應用程式在直向裝置方向和桌面模式下為全螢幕，就會套用這項設定。啟用可及性後，位置可以在頂端、中間和底部之間變更。這項設定會定義預設設定：
  • 選項 0 - 頂端
  • 選項 1 - 中心
  • 選項 2 - 底部
如果指定的值超出這個範圍，系統會假設為選項 0 (頂端)。

用途或情境
應用程式在桌上型電腦模式中的預設位置。

設定

本節列出所有設定，方便您在「設定」>「應用程式」>「螢幕比例」中，自訂及啟用使用者螢幕比例設定。

名稱 位置 類型 預設
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否啟用個別應用程式的使用者長寬比覆寫設定。

用途或情境
在「設定」 >「應用程式」 >「長寬比」中啟用長寬比設定功能。
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否要在使用者長寬比設定中啟用「覆寫應用程式的全螢幕設定」選項。

用途或情境
啟用使用者長寬比設定功能中的「全螢幕」選項。
這項設定會忽略應用程式的不可調整大小、顯示比例和螢幕方向限制。
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array 所有選項預設為啟用。
說明
設定應用程式的螢幕比例設定畫面和使用者螢幕比例覆寫選項。 必須與 config_userAspectRatioOverrideValues 的長度和順序相同。
如果變更，請一併更新備份與還原邏輯，以便在 UserAspectRatioBackupManager.java 中選擇最接近的值。

用途或情境
設定中顯示的字串對應。
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array 系統預設會使用所有 AOSP 字串。
說明
設定應用程式的螢幕比例設定畫面和使用者螢幕比例覆寫選項。 必須與 config_userAspectRatioOverrideEntries 的長度和順序相同。值必須與 PackageManager.UserMinAspectRatio 相對應。
如果變更，請一併更新備份與還原邏輯，以便在 UserAspectRatioBackupManager.java 中選擇最接近的值。

用途或情境
後端選項的對應項目 PackageManager.UserMinAspectRatio：
  • 應用程式預設 - 0
  • 分割畫面 - 1
  • 螢幕顯示比例 - 2
  • 4:3 - 3
  • 16:9 - 4
  • 3:2 - 5
  • 全螢幕 - 6
靜態淺色主題可繪項目 packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector 橫向摺疊式裝置大小的素材資源
說明
設定可用的可繪項目：


用途或情境
「設定」>「應用程式資訊」>「長寬比」中各選項下方的淺色主題靜態圖片。
靜態深色主題可繪項目 packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector 橫向摺疊式裝置大小的素材資源
說明
設定可用的可繪項目：


用途或情境
「設定」>「應用程式資訊」>「長寬比」中，每個選項下方的深色主題靜態圖片。
動態可繪項目
user_aspect_ratio_education.json		 packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON 橫向摺疊式大小的動態素材資源
說明
在 UserAspectRatioAppsPageProvider 中設定 Lottie 插圖。

用途或情境
應用程式清單中的動畫：依序前往「設定」>「應用程式」>「顯示比例」。

教育

本節列出所有設定，可讓使用者瞭解應用程式相容性功能。

名稱 位置 類型 預設
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
說明
設定是否為全螢幕應用程式啟用上下黑邊教育內容。

用途或情境
如要瞭解全螢幕應用程式的上下黑邊教育內容用途，請參閱圖 1。
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
說明
設定是否啟用擴充重新啟動對話方塊。

用途或情境
如要瞭解擴充重新啟動對話方塊的用途，請參閱圖 2。
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
說明
設定是否啟用有關可及性的額外教育資訊。

用途或情境
請參閱圖 3，瞭解可及性教育資訊的用途。
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
說明
設定是否啟用大小相容性重新啟動按鈕。

用途或情境
在視窗大小變更後，重新啟動無法調整大小的應用程式設定，例如進入分割畫面或旋轉螢幕時。
如要瞭解大小相容性重新啟動按鈕的使用案例，請參閱圖 4。
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
說明
設定活動邊界在工作中的百分比容許度下限，以隱藏大小相容性重新啟動按鈕。系統會忽略低於 0 或高於 100 的值。
100 是預設值，活動必須完全符合工作，才能隱藏大小相容性重新啟動按鈕。0 值表示系統一律會隱藏大小相容性重新啟動按鈕。

用途或情境
用於接近正方形的裝置，在使用者旋轉無法調整大小的應用程式時隱藏重新啟動按鈕，但重新啟動應用程式不會大幅改善 UI。

以下圖片顯示教育疊加層的用途：

全螢幕應用程式的上下黑邊教育內容

圖 1. 全螢幕應用程式的上下黑邊教育內容

擴充重新啟動對話方塊範例。

圖 2. 延長重新啟動對話方塊

可觸及性教育範例。

圖 3. 可及性教育。

大小相容性重新啟動按鈕的範例。

圖 4. 大小相容性重新啟動按鈕。