大屏设备应用兼容性设置指南

本页面提供了全面的设置指南和索引，用于介绍 Android 大屏应用兼容性配置叠加层。

显示

本部分列出了所有会影响展示级配置的配置设置。

名称 位置 类型 默认
ignoreOrientationRequest display_settings.xml config false
true 适用于大屏设备（>= 600dp）
说明
允许用户在指定显示屏上自由旋转固定方向 activity。
示例： 
          <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
说明
针对因摄像头缓冲区与应用窗口之间的方向不匹配而导致的问题，启用摄像头兼容性处理。
这包括强制旋转与摄像头连接的固定方向全屏 activity，并在分屏模式下显示提示。
可以通过按应用替换项停用强制旋转处理： OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

用例或上下文
通过强制旋转显示屏来修正旋转的相机预览，以匹配应用请求的屏幕方向。
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
说明
配置当启用相机兼容性处理功能且 activity 以全屏模式连接到相机时，activity 是否使用分屏宽高比。

使用情形或背景信息
通过将 activity 采用信箱模式调整为类似长条糖果的宽高比，修复拉伸的相机预览。
通常与横屏设备上启用的强制旋转处理 (config_isWindowManagerCameraCompatTreatmentEnabled 和 camera.enable_landscape_to_portrait) 一起使用，以通过为 activity 模拟竖屏直板式宽高比来修复拉伸的相机兼容性问题。
camera.enable_landscape_to_portrait 系统属性 Bool false
说明
控制OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT处理。
强制将相机输出画面剪裁并旋转 90 度，以在自然屏幕方向为横向的相机上模拟纵向自然屏幕方向。设备上所有横向摄像头的报告摄像头传感器方向均为纵向。许多应用都不会处理这种情况，而是显示经过拉伸的图像。

使用情形或上下文
启用相机 HAL 旋转和剪裁处理。如需详细了解处理方式，请参阅旋转、裁剪、缩放。
在 build 时将以下内容添加到您的 mk 文件中：PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
此处理需要设备在 HAL 中支持 SCALER_ROTATE_AND_CROP。请参阅 CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES。
如需有关 SCALER_ROTATE_AND_CROP 的 HAL 特定实现的指南，请参阅 metadata_definitions.xml。

背景和界面

本部分列出了应用于信箱模式层表面的所有配置设置，用于界面自定义或活动级别。

名称 位置 类型 默认
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
说明
为以信箱模式呈现的 activity 配置圆角半径。如果值小于 0，则启用圆角，半径等于设备底部角半径的最小值。默认值 0 会关闭 AppCompatLetterboxPolicy 中的圆角逻辑。

使用情形或背景信息
通常配置为与实体设备的圆角相匹配。
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
说明
配置是否启用半透明 activity 的特定信箱模式行为。

使用情形或背景信息
启用半透明 activity 或模态框，以便在信箱模式 activity 配置中以信箱模式显示并受到限制。该政策适用于 TransparentPolicy。
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
说明
配置是否为分屏恢复的 activity 启用发送兼容性假焦点。
这是必需的，因为某些游戏引擎会等待获得焦点，然后才绘制应用的内容，而多窗口模式默认不提供焦点。

使用情形或背景信息
一个旧版标志，用于为 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 可以自行实现此功能，但 AOSP 不会处理任何 bug。
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，并且请求模糊效果，但设备不支持模糊效果，或者未提供深色幕帘 Alpha 和模糊半径。


使用情形或背景信息
由于存在性能问题，此功能尚未发布。OEM 可以自行实现此功能，但 AOSP 不会处理任何 bug。
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
说明
为 R.integer.config_letterboxBackgroundType 中的选项 3 配置模糊半径。系统会忽略小于 0 的值，并使用 0。

使用情形或背景信息
由于存在性能问题，此功能尚未发布。OEM 可以自行实现此功能，但 AOSP 不会处理任何 bug。
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
说明
当为 R.integer.config_letterboxBackgroundType 选择选项 3 时，配置显示在壁纸信箱背景上的黑色半透明遮罩的 Alpha。 系统会忽略小于 0 或大于等于 1 的值，并改用 0.0（透明）。

使用情形或背景信息
由于存在性能问题，此功能尚未发布。OEM 可以自行实现此功能，但 AOSP 不会处理任何 bug。

可达性和定位

本部分列出了应用于无障碍功能 Activity 级窗口配置的所有配置设置。

名称 位置 类型 默认
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
说明
配置 activity 边界在其任务中的百分比的最小容差，以隐藏尺寸兼容性重启按钮。系统会忽略低于 0 或高于 100 的值。
100 是默认值，表示 activity 必须完全适合任务，才能隐藏大小兼容性重启按钮。值 0 表示始终隐藏大小兼容性重启按钮。

使用情形或背景信息
在接近正方形的设备中使用，用于在用户旋转不可调整大小的应用时隐藏重启按钮，但重启应用不会大幅改进界面。

以下图片展示了教育叠加层的应用场景：

针对全屏应用的竖屏模式教育

图 1. 针对全屏应用的竖屏模式教育

扩展的重新启动对话框示例。

图 2. 扩展的重新启动对话框

可达性教育示例。

图 3. “步行/开车可达地点”功能教育。

尺寸兼容性重启按钮的示例。

图 4. 尺寸兼容性重启按钮。