设备兼容模式

对于声明方向或可调整大小限制的应用，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()`。

优化

应用程序不应执行以下操作

在活动 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 兼容性定义文档指出，相机图像传感器“必须定向，使相机的长边与屏幕的长边对齐”。

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

使用应用程序不希望的相机方向启动活动，或在不同的相机或设备屏幕（对于可折叠设备）之间切换会导致相机预览对齐错误或失真。

在大屏幕可折叠设备上对齐错误和失真的相机预览。

优化

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

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

兼容性解决方法

当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 检测到应用在 1 秒内请求至少两个新方向，则系统认为这是一个方位无限循环，并应用覆盖。
	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()`。