设备兼容模式

Android 会为声明了方向或可调整大小限制的应用激活兼容模式。兼容模式可确保应用在大屏幕设备和可折叠翻盖手机上行为可接受，但可用性欠佳。

单应用替换设置使设备制造商、虚拟设备所有者¹和用户能够更改应用行为，以改善应用布局或防止应用在特定设备上崩溃。

Android 16

Android 16（API 级别 36）会忽略屏幕方向、纵横比和应用可调整大小限制，以改善最小宽度大于等于 600dp 的外形设备上的应用布局。

以下单应用替换设置对于目标 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

选择停用

您的应用可以以 API 级别 36 为目标，但选择停用 Android 16 行为，在这种情况下，OVERRIDE_ANY_ORIENTATION_TO_USER 不适用。

声明清单属性

要选择停用 API 级别 36 行为，请声明 PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY 清单属性。

要停用特定 Activity，请在 <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。

限制为纵向的应用无法在横向设备上使用。

优化

应用应支持所有设备和多窗口模式显示方向和尺寸。从您的应用布局和应用清单文件中移除所有方向和固定纵横比限制。

应用支持所有设备方向。

兼容性变通方法

如果一个具有固定方向或固定纵横比的应用在一个应用不直接支持窗口大小或方向的窗口中运行，Android 会将应用以信箱模式显示，以保持连续性。

从 Android 12（API 级别 31）开始并延续到 12L（API 级别 32），平台对信箱模式应用应用了各种增强功能。设备制造商实现了 UI 增强功能。您无需进行任何额外开发即可使您的应用受益于这些改进。

Android 12（API 级别 31）引入了以下美学增强功能，这些功能可由设备制造商配置：

圆角：应用窗口的角落看起来更精致。
系统栏透明度：覆盖在应用上的状态栏和导航栏是半透明的，使栏上的图标始终在信箱模式背景上可见。
可配置纵横比：应用的纵横比可以调整，以改善应用的外观。

图 2. 带有 UI 增强功能的信箱模式应用。

12L（API 级别 32）增加了以下功能改进：

可配置定位：在大屏幕上，设备制造商可以将应用定位到显示屏的左侧或右侧，从而使交互更容易。
重新设计的重启按钮：设备制造商可以为大小兼容模式的重启按钮赋予新外观，以便用户更好地识别。

Android 13（API 级别 33）添加了一个用户教育对话框，用于在屏幕上定位信箱模式应用或在分屏模式中包含信箱模式。

图 3. 带有用户教育对话框的信箱模式应用。

大小兼容模式

大小兼容模式是一种信箱模式，它保持应用纵横比并包含一个重启控件。该控件使用户能够重启应用并重新绘制显示屏。Android 会为不可调整大小的应用调用大小兼容模式。当 Activity 移动到与 Activity 尺寸不兼容的显示容器时，系统可能会重新缩放应用以至少在一个维度上填充设备显示屏。

可以触发大小兼容模式的设备配置更改包括：

设备旋转
可折叠设备折叠或展开
全屏和分屏显示模式之间的切换

问题

大小兼容模式通常适用于那些在方向或纵横比上受到限制，并被配置（或由系统确定）为不可调整大小的 Activity。

如果您的应用符合以下任何条件，则被认为是可调整大小的，并且不会进入大小兼容模式：

通过 resizeableActivity="true" 可调整大小
支持画中画 (PIP) 模式
是嵌入式
设备制造商应用了 FORCE_RESIZE_APP 单应用替换设置（应用设置的属性将被忽略）

如果您的应用不符合任何条件，则被认为不可调整大小，并可能进入大小兼容模式。

不可调整大小的应用在多窗口模式下崩溃。

优化

应用应支持所有显示尺寸。通过将应用清单中 <activity> 或 <application> 元素的 android:resizeableActivity 属性设置为 true，使您的应用可调整大小。为您的应用设计响应式/自适应布局。有关更多信息，请参阅支持不同的显示尺寸和支持多窗口模式。

应用可在所有窗口大小下运行。

兼容性变通方法

当系统确定通过重新缩放应用以至少在一个维度上填充显示窗口可以改善信箱模式应用显示时，Android 会将应用置于大小兼容模式。系统会显示一个重启控件，该控件会重新创建应用进程，从而重新创建 Activity 并重新绘制显示。另请参阅进程和线程概览。

仅支持纵向的应用在横向显示时以信箱模式显示，并通过重启控件重新缩放。

闪烁循环

当一个应用不支持所有显示方向时，它可能会在配置更改发生时反复请求新的方向，从而创建一个无限循环，使显示屏闪烁或应用无限旋转。

问题

在 Android 12（API 级别 31）及更高版本上，设备制造商可以将其设备配置为忽略应用指定的方向限制，并强制执行兼容模式。例如，当 Activity 显示在设备横向平板大小的内部屏幕上时，可折叠设备可能会忽略 Activity 的 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)，并继续无限循环。

仅支持横向的应用在纵向显示屏上重复调用 `Activity#setRequestedOrientation()`。

优化

应用不应执行以下操作：

在 Activity 的 onCreate() 方法中通过 Activity#setRequestedOrientation() 设置默认方向，因为方向请求可能由于未处理的配置更改而意外触发
假定设备的自然方向（ROTATION_0）是纵向
根据与当前窗口大小无关的信号设置方向，例如 Display#getRotation()、是否存在 FoldingFeature 或已弃用的 API。

应用处理配置更改，没有方向限制，因此不会进入闪烁循环。

兼容性变通方法

在以下情况下，Android 会忽略对 Activity#setRequestedOrientation() 的调用：

Activity 已从先前对该方法的调用重新启动，或者已启用相机兼容强制旋转处理（请参阅下面的相机预览）。

设备制造商可以使用 OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION 将此行为应用于应用。
Activity 在一秒内发出了两次以上的方向请求，这表明发生了循环。在循环中的两次请求中，Android 使用最大化应用显示区域的那个。

设备制造商可以使用 OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED 将此行为应用于应用。
虚拟设备所有者已在特定设备上覆盖了方法调用。

相机预览

相机应用的相机预览（或取景器）在平板电脑、笔记本电脑和可折叠显示屏上可能会错位或失真。

问题

Android 兼容性定义文档指出，相机图像传感器“必须定向，以便相机的长尺寸与屏幕的长尺寸对齐。”

应用通常假定设备方向和相机传感器方向是纵向的——这在标准手机上是一个合理的假设。但是，平板电脑和笔记本电脑及其相机传感器的自然方向可以是横向的。此外，像可折叠设备这样的新外形设备可以有多种自然方向和多个不同方向的相机传感器。

以应用不期望的相机方向启动 Activity 或在不同相机或设备屏幕（对于可折叠设备）之间切换可能会导致相机预览错位或失真。

大屏幕可折叠设备上的相机预览错位和失真。

优化

相机应用必须正确识别和管理设备方向和相机传感器方向，以呈现正确对齐和缩放的相机预览。应用必须计算设备旋转、传感器旋转和屏幕或窗口纵横比，然后将结果应用于相机预览。有关详细指导，请参阅相机预览和相机取景器简介。

相机预览在所有设备方向上均正确对齐和缩放。

兼容性变通方法

当 Display#getRotation() 返回 Surface.ROTATION_0 时，设备处于自然方向。系统从设备的自然方向计算 CameraCharacteristics.SENSOR_ORIENTATION。Android 将纵向限制应用的纵向窗口与设备的自然方向对齐，这是大多数应用所期望的。当传感器方向为横向且相机预览为纵向时，Android 还会裁剪相机传感器图像。具体的变通方法包括：

强制旋转纵向限制应用的相机预览：限制为纵向的应用期望设备的自然方向和相机传感器方向为纵向。但是，在 Android 12（API 级别 31）及更高版本上，如果设备制造商忽略方向规范，应用可以在多种设备方向下运行。

当纵向受限应用连接到相机时，Android 会强制旋转应用，使应用纵向窗口与设备的自然方向对齐。

在某些平板电脑上（请参阅参考设备），应用纵向窗口会旋转到全屏纵向，以与设备的自然方向对齐。强制旋转后，应用会占据整个屏幕。

平板电脑 — 纵向受限应用的强制旋转。

在可折叠设备的横向内屏上（请参阅参考设备），仅支持纵向的 Activity 会旋转为横向，以与展开后的自然方向对齐。强制旋转后，应用会以信箱模式显示。

可折叠设备 — 纵向限制应用的强制旋转。应用也以信箱模式显示。

注意： 如果您的应用具有响应能力并处理纵向和横向，则不会发生强制旋转。
内部前置摄像头裁剪：某些可折叠设备的内部前置摄像头传感器处于横向。除了在可折叠内部显示屏上强制旋转摄像头预览外，Android 还会裁剪内部前置（横向）摄像头视野，以便传感器捕获与设备方向相反的视图。
强制刷新相机预览：系统在强制旋转后循环执行 Activity 方法 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

有关更多信息，请参阅支持多窗口模式。

滥用视图 API

已弃用的 API 错误计算应用边界。应用内容超出屏幕。

优化

切勿依赖物理显示尺寸来定位 UI 元素。将您的应用迁移到基于 WindowMetrics 的 API，包括以下 WindowManager API：

API 正确计算应用窗口指标。

兼容性变通方法

两个替换设置调整已弃用的 Display API 和误用的 View API，以返回应用边界：ALWAYS_SANDBOX_DISPLAY_APIS 适用于 Display API；OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS 适用于 View API。ALWAYS_SANDBOX_DISPLAY_APIS 也默认应用于符合大小兼容模式的应用。

透明 Activity

透明 Activity 是透明背景样式的结果，例如：

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

与对话框相关的主题，例如 Theme.MaterialComponents.Dialog，可以包含使 Activity 透明的样式。

透明 Activity 不会覆盖所有可用的显示空间，这使得它们难以管理，因为可用的显示区域可能会根据设备旋转、设备折叠和展开以及多窗口模式等配置更改而改变。

问题

透明 Activity 应符合任务 Activity 堆栈中透明 Activity 下的第一个不透明 Activity 的边界。然而，启动权限对话框的不透明 Activity 可以是一个跳板（一个启动另一个 Activity 然后消失的 Activity）；因此，系统无法确定启动透明权限对话框 Activity 的跳板 Activity 的边界。

由于 Activity 是从跳板启动的，因此对话框位置错误。

优化

透明 Activity 会从其在任务 Activity 堆栈中的最顶部不透明 Activity 继承所有限制。不透明 Activity 必须在透明 Activity 的整个生命周期内（从 Activity 创建到销毁）都可用。因此，不要从跳板 Activity 启动权限请求。

如果跳板 Activity 启动权限请求，用户可能无法看到权限对话框，因为跳板 Activity 将在用户有机会响应对话框之前被销毁，并且对话框 Activity 的尺寸和位置可能计算不正确。

应用应始终从保持可见直到用户做出权限决定的 Activity 启动权限请求。

圆角

Activity 可以是透明的，因为样式指定了背景透明度，或者因为 Activity 的内容没有填满可用的显示空间。如果透明 Activity 填满了可用的显示空间，系统会在设备制造商配置后自动对 Activity 应用圆角。但是，如果透明 Activity（如权限对话框）没有填满可用空间，则由您决定是否应用圆角。

权限对话框不会填满可用的显示空间，因为对话框布局通常使用 LayoutParams.WRAP_CONTENT 而不是 LayoutParams.MATCH_PARENT。

带圆角的对话框正确地定位在可见的启动 Activity 上方。

兼容性变通方法

保持启动对话框 Activity 的 Activity 可见，直到用户响应对话框为止。

系统确保透明 Activity 从 Activity 堆栈中透明 Activity 下方的第一个不透明 Activity 继承所有限制，包括与以下内容相关的限制：

大小兼容模式
方向
纵横比

Unity 游戏

Unity 游戏可以在 Android 全屏或多窗口模式下运行。但是，许多 Unity 游戏在应用进入多窗口模式时会失去焦点并停止绘制内容。

问题

Unity 在 Unity 2019.4 中添加了 Resizable Window 选项，以支持 Android 上的多窗口模式。然而，最初的实现没有正确响应多窗口模式下的 Activity 生命周期，导致 UnityPlayer 在应用失去焦点时暂停播放。播放器渲染了黑屏或游戏的最后一帧冻结画面。只有当用户点击屏幕时，游戏才会恢复。许多使用 Unity 引擎的应用都面临此问题，并在多窗口模式下渲染为黑窗口。

游戏在多窗口模式下失去焦点并渲染为黑窗口。

优化

将 Unity 升级到 2019.4.40 或更高版本，然后重新导出您的游戏。在Android 播放器设置中保持选中 Resizable Window 选项，否则即使游戏在多窗口模式下完全可见，游戏也会在失去焦点时暂停。

游戏在多窗口模式下即使失去焦点也能正确渲染内容。

兼容性变通方法

设备制造商可以应用 OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS 单应用替换设置，为多窗口模式下的应用提供一个伪焦点事件。该替换设置使 Activity 能够重新绘制内容，而不会出现黑屏。

桌面窗口化

当应用在桌面窗口化环境中运行时，它们可能会遇到额外的兼容模式。

方向锁定的应用可以自由调整大小。即使 Activity 锁定为纵向，用户仍可以将应用调整为横向。

Animation of a portrait app being resized to landscape.

方向锁定的应用仍然可以自由调整大小。

但是，如果 Activity 声明为不可调整大小（resizeableActivity = false），则 Activity UI 会在保持相同纵横比的同时进行缩放。

Animation of app being resized. UI scales to fill the desktop window.

声明为不可调整大小的 Activity 会将其 UI 进行缩放。

桌面窗口化中的相机预览

当桌面窗口化中的应用启动相机预览时，取景器会将其 UI 缩放，同时保持其原始纵横比。应用窗口的其余部分可以自由调整大小。

调整带有相机取景器的窗口大小

测试您的应用是否存在兼容性问题

要测试您的应用并了解它在不同外形尺寸上的行为，请利用以下资源：

设备流式传输：要在 Google 数据中心托管的生产设备（包括参考设备）上测试您的应用，请参阅由 Firebase 提供支持的 Android 设备流式传输
Android Studio 中的模拟器：有关为参考设备创建模拟器的信息，请参阅创建和管理虚拟设备
Android Studio 可调整大小模拟器：有关访问虚拟设备的信息，请参阅在 Android 模拟器上运行应用

信箱模式

验证每个 Activity 是否可以使用应用可用的所有显示空间。首先，在您的测试文件夹中声明以下代码：

Kotlin

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

Java

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

然后运行测试以断言行为并确保目标 Activity 未以信箱模式显示：

Kotlin

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

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

Java

@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(isLetterboxed(activity));
            });
        }
}DeviceCompatibilityModeTestJavaSnippets.java

理想情况下，只运行此类测试直到它通过并断言您的应用 Activity 占据应用可用的整个显示空间。在所有设备类型上测试您的应用，以确保行为一致。

单应用替换设置

Android 提供了更改应用配置行为的替换设置。例如，FORCE_RESIZE_APP 替换设置指示系统绕过大小兼容模式并调整应用大小以适应显示尺寸，即使在应用清单中指定了 resizeableActivity="false"。

设备制造商将替换设置应用于特定大屏幕设备上的选定应用或所有应用。在 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>
```
全屏选项将从设备设置中的纵横比选项列表中移除。用户将无法对您的应用应用全屏替换。

注意： 如果 PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE 为 false，此属性无效。

将此属性设置为 true 无效。

为所有屏幕优化您的应用：不要在您的应用中设置纵横比限制。使用窗口大小类根据可用的显示空间量支持不同的布局。

设备单应用替换设置

设备制造商和虚拟设备所有者（选定的受信任和特权应用）在特定设备上逐应用地应用替换设置，包括平板电脑、可折叠设备、ChromeOS 设备和车载显示器。参考设备可能会默认将其中一些替换设置应用于各种应用。

应用可以停用大多数替换设置（请参阅下面的单应用替换设置表）。

您可以使用兼容性框架测试您的应用，启用或禁用替换设置（请参阅兼容性框架工具）。启用后，替换设置适用于整个应用。

您还可以使用 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	如果启用（默认），则将替换范围限制为仅限纵向的 Activity。
	OVERRIDE_MIN_ASPECT_RATIO_SMALL	349045028	将最小纵横比更改为 4:3。
	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	当 Activity 具有未定义的方向时，将方向覆盖为纵向。
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	当 Activity 具有未定义的方向时，将方向覆盖为 `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	如果检测到循环，则忽略 Activity 重新启动时重复的方向请求。如果 Android 检测到应用在一秒内请求了至少两个新方向，系统会将其视为旋转无限循环并应用替换。
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	通过禁用设备制造商忽略方向请求设置来防止信箱模式。
沙盒 API	NEVER_SANDBOX_DISPLAY_APIS	184838306	防止更改任何显示 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。

如何优化应用

使用响应式/自适应布局，使应用能够适应所有显示尺寸和纵横比。请参阅支持不同的显示尺寸。

如何禁用或选择停用替换设置

将属性标志 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

所有强制给定最小纵横比的替换设置的守门员。

应用如何实现与替换设置相同的结果

在 Activity 或应用级别设置 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

限制应用设置，这些设置强制对仅支持纵向的 Activity 强制给定最小纵横比。默认情况下启用，并且仅在 OVERRIDE_MIN_ASPECT_RATIO 也启用时生效。

设备兼容模式 使用收藏夹保持井然有序 根据您的偏好保存和分类内容。

Android 16

选择停用

声明清单属性

参考设备

常见兼容性问题

信箱模式

问题

限制为纵向的应用无法在横向设备上使用。

优化

应用支持所有设备方向。

兼容性变通方法

大小兼容模式

问题

不可调整大小的应用在多窗口模式下崩溃。

优化

应用可在所有窗口大小下运行。

兼容性变通方法

仅支持纵向的应用在横向显示时以信箱模式显示，并通过重启控件重新缩放。

闪烁循环

问题

仅支持横向的应用在纵向显示屏上重复调用 Activity#setRequestedOrientation()。

优化

应用处理配置更改，没有方向限制，因此不会进入闪烁循环。

兼容性变通方法

相机预览

问题

大屏幕可折叠设备上的相机预览错位和失真。

优化

相机预览在所有设备方向上均正确对齐和缩放。

兼容性变通方法

平板电脑 — 纵向受限应用的强制旋转。

可折叠设备 — 纵向限制应用的强制旋转。应用也以信箱模式显示。

常见滥用 API

问题

已弃用的 API 错误计算应用边界。应用内容超出屏幕。

优化

API 正确计算应用窗口指标。

兼容性变通方法

透明 Activity

问题

由于 Activity 是从跳板启动的，因此对话框位置错误。

优化

圆角

带圆角的对话框正确地定位在可见的启动 Activity 上方。

兼容性变通方法

Unity 游戏

问题

游戏在多窗口模式下失去焦点并渲染为黑窗口。

优化

游戏在多窗口模式下即使失去焦点也能正确渲染内容。

兼容性变通方法

桌面窗口化

方向锁定的应用仍然可以自由调整大小。

声明为不可调整大小的 Activity 会将其 UI 进行缩放。

桌面窗口化中的相机预览

调整带有相机取景器的窗口大小

测试您的应用是否存在兼容性问题

信箱模式

Kotlin

Java

Kotlin

Java

单应用替换设置

用户单应用替换设置

设备单应用替换设置

FORCE_RESIZE_APP

应用如何实现与替换设置相同的结果

如何优化应用

如何禁用或选择停用替换设置

用于调整替换设置的属性标志

用于测试替换设置的 adb 命令

FORCE_NON_RESIZE_APP

应用如何实现与替换设置相同的结果

如何优化应用

如何禁用或选择停用替换设置

用于调整替换设置的属性标志

用于测试替换设置的 adb 命令

OVERRIDE_MIN_ASPECT_RATIO

应用如何实现与替换设置相同的结果

设备兼容模式

仅支持横向的应用在纵向显示屏上重复调用 `Activity#setRequestedOrientation()`。