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

本页面提供了全面的设置指南和索引，用于介绍 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_isCameraCompatSimulateRequestedOrientationTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool true
说明
表示是否启用摄像头兼容性处理（模拟应用的请求方向）。此处理的目的是缓解因相机缓冲区与应用窗口之间的方向不匹配而导致的问题。这包括以下方面：将与相机相关的固定屏幕方向 Activity 采用黑边模式、剪裁相机缓冲区（旋转和剪裁）以及对显示屏旋转进行沙盒处理，以匹配应用的预期屏幕方向。

用例或情境
模拟相机 Activity 的请求屏幕方向：
  • 自由窗口模式
  • 固定屏幕方向请求，但不是 locked 或 nosensor 模式

在 Android 17 及更高版本中，此设置会停用 config_isWindowManagerCameraCompatTreatmentEnabled 中的强制旋转处理，并统一固定屏幕方向的相机应用的显示旋转沙盒化、信箱模式和相机旋转并剪裁政策。
config_isCameraCompatSimReqOrientationLandscapeTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
说明
表示是否为横向摄像头启用了模拟应用所请求方向的摄像头兼容性处理。此处理的目的是缓解因应用对竖屏相机传感器进行硬编码而导致的问题。处理方式包括：对与摄像头相关的固定方向 activity 进行信箱模式处理、裁剪摄像头缓冲区（旋转并裁剪）、将传感器方向设为纵向，以及对显示旋转进行沙盒处理，以匹配应用的预期方向。

使用情形或背景信息
在 Android 17 及更高版本中，此处理方式与 config_isCameraCompatSimulateRequestedOrientationTreatmentEnabled 的模拟请求的方向处理方式相同，但适用于摄像头方向为横向的设备。

背景和界面

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

名称 位置 类型 默认
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。
config_enableSelfKillRecoveryBetweenInternalDisplays frameworks/base/core/res/res/values/config.xml Bool false
说明
当 true 时，显示屏在内部显示屏之间的移动不会免于自杀恢复逻辑。

使用情形或背景信息
在 Android 17 及更高版本中，自杀恢复进程仅针对涉及外部显示器的显示屏移动启用。不过，此流程也适用于内外屏密度不同的可折叠设备。此配置可为这些设备启用该流程。

可达性和定位

本部分列出了应用于无障碍功能 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. 尺寸兼容性重启按钮。