设备兼容性模式

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

每个应用的覆盖设置使设备制造商能够更改应用行为以改善用户体验或防止应用在特定设备上崩溃。

参考设备

由于配置异常或应用不太支持的配置，以下设备可能需要每个应用的覆盖设置

平板电脑：某些平板电脑（例如 Pixel 平板电脑）的自然方向是横向。当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 会为确定为不可调整大小的应用调用尺寸兼容性模式。当活动移动到与活动尺寸不兼容的显示容器时，系统可能会重新调整应用的大小，以至少在一个维度上填充设备显示屏。

可能触发尺寸兼容性模式的设备配置更改包括：

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

问题

尺寸兼容性模式通常适用于在方向或纵横比方面受到限制，并且配置为（或由系统确定为）不可调整大小的活动。

如果您的应用满足以下任何条件，则它被视为可调整大小——并且不会进入尺寸兼容性模式：

使用resizeableActivity="true"可调整大小
支持画中画 (PIP)模式
已嵌入
应用了设备制造商应用的FORCE_RESIZE_APP每个应用覆盖（忽略应用设置的属性）

如果您的应用不满足任何条件，则它被视为不可调整大小，并且可能会进入尺寸兼容性模式。

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

优化

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

应用可在所有窗口尺寸下运行。

兼容性解决方法

当系统确定可以通过重新调整应用的大小以至少在一个维度上填充显示窗口来改善带黑边应用的显示时，Android 会将应用置于尺寸兼容性模式。系统会显示一个重启控件，该控件会重新创建应用进程，重新创建活动并重绘显示内容。另请参阅进程和线程概述。

仅限纵向模式的应用在横向模式下带黑边，通过重启控件重新缩放。

闪烁循环

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

问题

在 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)，并继续无限循环。

纵向显示上的仅限横向模式的应用会重复调用`Activity#setRequestedOrientation()`。

优化

应用不应执行以下操作：

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

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

兼容性解决方法

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

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

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

设备制造商可以将此行为应用于带有OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED的应用。

相机预览

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

问题

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

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

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

在大屏幕可折叠设备上相机预览错位且变形。

优化

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

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

兼容性解决方法

当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

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

误用的视图 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 也默认应用于符合尺寸兼容性模式的应用。

透明活动

透明活动是透明背景样式的结果，例如

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

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

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

问题

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

对话框位置错误，因为活动是从跳板启动的。

优化

透明活动从任务活动堆栈中下方最顶层的不透明活动继承其约束。不透明活动必须在透明活动的整个生命周期内可用，从活动创建到销毁。因此，不要从跳板活动启动权限请求。

如果跳板活动启动权限请求，用户可能无法看到权限对话框，因为在用户有机会响应对话框之前，跳板活动已被销毁，并且对话框活动的大小和位置可能计算错误。

应用应始终从在用户做出权限决定之前保持可见的活动启动权限请求。

圆角

活动可能由于指定背景透明度的样式而透明，或者因为活动的內容未填满可用的显示空间。如果透明活动填满了可用的显示空间，则系统会在设备制造商配置为这样做时自动将圆角应用于活动。但是，如果透明活动（如权限对话框）未填满可用空间，则由您决定是否应用圆角。

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

带有圆角的对话框正确地定位在可见的启动活动之上。

兼容性解决方法

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

系统确保透明活动继承活动堆栈中透明活动下方第一个不透明活动的所有约束，包括与以下内容相关的约束：

尺寸兼容性模式
方向
纵横比

Unity 游戏

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

问题

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

游戏在多窗口模式下失去焦点并呈现为黑色窗口。

优化

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

即使在失去焦点时，游戏也能在多窗口模式下正确呈现内容。

兼容性解决方法

设备制造商可以应用OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS每个应用覆盖，以便在多窗口模式下向应用提供虚假焦点事件。此覆盖允许活动重新绘制内容，而不会变黑。

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

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

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

加黑边

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

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 提供覆盖来更改应用的配置行为。例如，FORCE_RESIZE_APP覆盖指示系统绕过尺寸兼容性模式并将应用调整大小以适应显示尺寸，即使在应用清单中指定了resizeableActivity="false"。

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

警告：如果PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE为false，则此属性无效。

将此属性设置为true无效。

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

设备制造商应用级别的覆盖

设备制造商会在选定设备上按应用进行覆盖。参考设备默认情况下可能会将某些覆盖应用于各种应用。

应用可以选择退出大多数覆盖（请参见下面的应用级别覆盖表）。

您可以使用兼容性框架测试启用或禁用覆盖的应用（请参见兼容性框架工具）。启用后，覆盖将应用于整个应用。

您还可以使用Android 调试桥 (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	防止更改任何显示 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:resizeableActivity=false），请将android.supports_size_changes元数据标志设置为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

所有强制给定最小纵横比的覆盖的守门人。

应用如何实现与覆盖相同的結果

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

限制强制为仅纵向模式的活动提供给定最小纵横比的应用设置。默认启用，仅当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

启用以下覆盖以覆盖任何方向

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

应用如何实现与覆盖相同的結果

设置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_USER

启用应用以填充可用的显示空间。覆盖应用清单中指定的任何方向、可调整大小和纵横比限制。还会忽略对Activity#setRequestedOrientation()的任何调用。

应用如何实现与覆盖相同的結果

不要设置android:screenOrientation清单属性，或将属性设置为"user"。
将android:resizeableActivity清单属性设置为true。

注意：如果resizeableActivity设置为true，则会忽略android:minAspectRatio和android:maxAspectRatio的设置。
在小型屏幕上，要在禁用多窗口模式（使用android:resizeableActivity=false）的同时支持应用调整大小，请将android.supports_size_changes元数据标志设置为true。不要设置minAspectRatio和maxAspectRatio。

注意：在 Android 12（API 级别 31）上，所有应用都在大屏幕（中等或扩展的窗口尺寸类）上以多窗口模式运行，无论应用配置如何。请参阅支持多窗口模式。

如何优化应用

启用您的应用以支持所有方向；不要在应用的清单中设置screenOrientation规范。通过将应用清单中的android:resizeableActivity属性设置为true来支持应用可调整大小、多窗口模式和所有显示纵横比。请参阅支持不同的屏幕尺寸。

设备兼容性模式

参考设备

常见的兼容性问题

信箱式显示

问题

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

优化

应用支持所有设备方向。

兼容性解决方法

尺寸兼容性模式

问题

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

优化

应用可在所有窗口尺寸下运行。

兼容性解决方法

仅限纵向模式的应用在横向模式下带黑边，通过重启控件重新缩放。

闪烁循环

问题

纵向显示上的仅限横向模式的应用会重复调用Activity#setRequestedOrientation()。

优化

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

兼容性解决方法

相机预览

问题

在大屏幕可折叠设备上相机预览错位且变形。

优化

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

兼容性解决方法

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

可折叠设备 — 强制旋转仅限纵向模式的应用。应用也会加黑边。

常用误用 API

问题

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

优化

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

兼容性解决方法

透明活动

问题

对话框位置错误，因为活动是从跳板启动的。

优化

圆角

带有圆角的对话框正确地定位在可见的启动活动之上。

兼容性解决方法

Unity 游戏

问题

游戏在多窗口模式下失去焦点并呈现为黑色窗口。

优化

即使在失去焦点时，游戏也能在多窗口模式下正确呈现内容。

兼容性解决方法

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

加黑边

Kotlin

Java

Kotlin

Java

每个应用的覆盖

用户应用级别的覆盖

设备制造商应用级别的覆盖

FORCE_RESIZE_APP

应用如何实现与覆盖相同的結果

如何优化应用

如何禁用或选择退出覆盖

用于调整覆盖的属性标志

用于测试覆盖的 adb 命令

FORCE_NON_RESIZE_APP

应用如何实现与覆盖相同的結果

如何优化应用

如何禁用或选择退出覆盖

用于调整覆盖的属性标志

用于测试覆盖的 adb 命令

OVERRIDE_MIN_ASPECT_RATIO

应用如何实现与覆盖相同的結果

如何优化应用

如何禁用或选择退出覆盖

用于调整覆盖的属性标志

用于测试覆盖的 adb 命令

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

应用如何实现与覆盖相同的結果

如何优化应用

如何禁用或选择退出覆盖

纵向显示上的仅限横向模式的应用会重复调用`Activity#setRequestedOrientation()`。