设备兼容模式

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

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

Android 16

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

以下单应用替换设置对于目标 API 级别 36 的应用无效:

选择停用

您的应用可以以 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。

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

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

优化

应用应支持所有显示尺寸。通过将应用清单中 <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 的 onCreate() 方法中通过 Activity#setRequestedOrientation() 设置默认方向,因为方向请求可能由于未处理的配置更改而意外触发
  • 假定设备的自然方向(ROTATION_0)是纵向
  • 根据与当前窗口大小无关的信号设置方向,例如 Display#getRotation()、是否存在 FoldingFeature已弃用的 API

兼容性变通方法

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

相机预览

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

问题

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

优化

切勿依赖物理显示尺寸来定位 UI 元素。将您的应用迁移到基于 WindowMetrics 的 API,包括以下 WindowManager 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(如权限对话框)没有填满可用空间,则由您决定是否应用圆角。

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

兼容性变通方法

保持启动对话框 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.

桌面窗口化中的相机预览

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

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

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

信箱模式

验证每个 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()
    }
}

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();
}

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

Kotlin

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

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

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));
            });
        }
}

理想情况下,只运行此类测试直到它通过并断言您的应用 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>
    

    全屏选项将从设备设置中的纵横比选项列表中移除。用户将无法对您的应用应用全屏替换。

    将此属性设置为 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:resizeableActivityandroid.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 APIView 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 也启用时生效。

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

请参阅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_PORTRAIT_ONLY <package>

要移除替换设置

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_MIN_ASPECT_RATIO_SMALL

将 Activity 的最小纵横比设置为小值 (4:3)。

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

请参阅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_SMALL <package>

要移除替换设置

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_MIN_ASPECT_RATIO_SMALL

将 Activity 的最小纵横比设置为小值 (4:3)。

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

请参阅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_SMALL <package>

要移除替换设置

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

将 Activity 的最小纵横比设置为中等值 (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

将 Activity 的最小纵横比设置为大值 (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

启用以下替换设置以覆盖任何方向:

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

设置 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()Activity#getRequestedOrientation() 的任何调用。

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

  • 不要设置 android:screenOrientation 清单属性,或将属性设置为 "user"

  • android:resizeableActivity 清单属性设置为 true

  • 在小屏幕上,为了在禁用多窗口模式的情况下支持应用大小调整(使用 android:resizeableActivity=false),将 android.supports_size_changes 元数据标志设置为 true不要设置 minAspectRatiomaxAspectRatio

如何优化应用

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

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

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

要应用替换设置

adb shell am compat enable OVERRIDE_ANY_ORIENTATION_TO_USER <package>

要移除替换设置

adb shell am compat disable OVERRIDE_ANY_ORIENTATION_TO_USER <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT

为包中的所有 Activity 启用纵向。除非启用 OVERRIDE_ANY_ORIENTATION,否则仅在 Activity 未指定其他固定方向时使用此替换。

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

请参阅OVERRIDE_ANY_ORIENTATION

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

要应用替换设置

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

要移除替换设置

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR

为包中的所有 Activity 启用nosensor 方向。除非启用 OVERRIDE_ANY_ORIENTATION,否则仅在 Activity 未指定其他固定方向时使用此替换。

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

请参阅OVERRIDE_ANY_ORIENTATION

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

要应用替换设置

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

要移除替换设置

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

为包中的所有 Activity 启用reverseLandscape 方向。除非启用 OVERRIDE_ANY_ORIENTATION,否则仅在 Activity 未指定其他固定方向时使用此替换。

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

请参阅OVERRIDE_ANY_ORIENTATION

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

要应用替换设置

adb shell am compat enable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

要移除替换设置

adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAITOVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOROVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE 替换设置为仅在相机连接处于活动状态时生效。

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

请参阅OVERRIDE_ANY_ORIENTATION

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

请参阅OVERRIDE_ANY_ORIENTATION

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

要应用替换设置

adb shell am compat enable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

要移除替换设置

adb shell am compat disable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION

在满足以下条件时,将显示方向限制为横向自然方向:

  • Activity 全屏显示
  • 选择停用组件属性 PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE 未启用
  • 显示屏已启用设备制造商忽略方向请求设置
  • 显示屏的自然方向是横向

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

不适用。问题应在应用逻辑中解决。

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

将属性标志 PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE 设置为 false

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

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

要移除替换设置

adb shell am compat disable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION

启用兼容性策略,该策略跳过响应应用调用 Activity#setRequestedOrientation() 更新应用方向,当应用正在重新启动或具有活动的相机兼容性处理时。

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

将属性标志 PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION 设置为 true

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

将属性标志 PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION 设置为 false

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

<property android:name="android.window.PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION"
  android:value="true|false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

要移除替换设置

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED

启用兼容性策略,该策略忽略应用在 Activity 未因固定方向而以信箱模式显示时,在一秒内两次以上调用 Activity#setRequestedOrientation() 所请求的方向。

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

不适用。问题应在应用逻辑中解决。

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

将属性标志 PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED 设置为 false

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

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED"
  android:value="false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

要移除替换设置

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_RESPECT_REQUESTED_ORIENTATION

将包从可由设备制造商为显示区域或整个显示屏启用的忽略方向请求行为中排除。

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

不适用。问题应在应用逻辑中解决。

如何优化应用

请参阅OVERRIDE_ANY_ORIENTATION

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

无法选择停用。如果应用与已启用设备制造商忽略方向请求设置的设备不兼容,禁用此替换可能存在风险。请联系 Android 开发者关系团队以禁用此替换。

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

此替换没有属性标志。

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

要应用替换设置

adb shell am compat enable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

要移除替换设置

adb shell am compat disable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

注意:命令仅暂时应用或移除替换设置。

NEVER_SANDBOX_DISPLAY_APIS

强制包在信箱模式或大小兼容模式 Activity 中永远不应用 Display API 沙盒。 Display API 继续提供显示区域边界。

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

通过将 android:resizeableActivity 清单属性设置为 true 或将 android.supports_size_changes 元数据标志设置为 true 来声明 Activity 可调整大小。

如何优化应用

声明为完全可调整大小的应用不应依赖显示尺寸来定位 UI 元素。将您的应用迁移到提供 WindowMetrics 的最新 API。如果您正在使用 Jetpack Compose,请利用 WindowSizeClass API 根据应用在当前显示屏上的屏幕区域大小来绘制 UI。请参阅使用窗口大小类

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

无法选择停用。从已弃用的 API 迁移。

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

此替换没有属性标志。

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

要应用替换设置

adb shell am compat enable NEVER_SANDBOX_DISPLAY_APIS <package>

要移除替换设置

adb shell am compat disable NEVER_SANDBOX_DISPLAY_APIS <package>

注意:命令仅暂时应用或移除替换设置。

ALWAYS_SANDBOX_DISPLAY_APIS

强制包始终应用 Display API 沙盒,无论窗口模式如何。Display API 始终提供应用边界。

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

通过将 android:resizeableActivity 属性设置为 false 或将 android.supports_size_changes 元数据标志设置为 false 来声明 Activity 不可调整大小。

如何优化应用

声明为完全可调整大小的应用不应依赖显示尺寸来定位 UI 元素。将您的应用从已弃用的 API 迁移到提供 WindowMetrics 的最新 API。请参阅WindowMetricsCalculator

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

无法选择停用。从已弃用的 API 迁移。

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

此替换没有属性标志。

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

要应用替换设置

adb shell am compat enable ALWAYS_SANDBOX_DISPLAY_APIS <package>

要移除替换设置

adb shell am compat disable ALWAYS_SANDBOX_DISPLAY_APIS <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS

强制包将以下 View API 沙盒化到 Activity 边界:

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

通过使用提供应用窗口边界和相对于应用窗口偏移量的 API,而不是设备显示边界和相对于设备显示偏移量的 API,在应用程序代码中解决此问题。

如何优化应用

应用应使用 View API,并考虑到应用可能应用信箱模式和多窗口模式。请参阅WindowMetricsCalculator

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

将属性标志 PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS 设置为 false

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

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS"
  android:value="false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

要移除替换设置

adb shell am compat disable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

禁用强制旋转。改善某些应用的用户体验。

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

将属性标志 PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION 设置为 false

如何优化应用

不要依赖缓存的相机传感器方向或设备信息。有关相机兼容性指南,请参阅相机取景器简介在相机应用中支持可调整大小的曲面

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

将属性标志 PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION 设置为 true

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

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION"
  android:value="true|false"/>

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

要应用移除强制旋转的替换设置

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

要移除允许强制旋转的替换设置

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH

禁用强制旋转后的 Activity 刷新。当刷新导致应用状态丢失时,改善用户体验。

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

将属性标志 PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH 设置为 false

如何优化应用

请参阅OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

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

将属性标志 PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH 设置为 true

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

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH"
  android:value="true|false"/>

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

要应用移除 Activity 刷新的替换设置

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

要移除允许 Activity 刷新的替换设置

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

使其应用的包在相机兼容强制旋转后,使用 onResume()onPause()onResume() 循环而不是 onResume()onStop()onResume() 进行 Activity 刷新。

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

将属性标志 PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE 设置为 true

如何优化应用

请参阅OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

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

将属性标志 PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE 设置为 false

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

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE"
  android:value="true|false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

要移除替换设置

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT

当纵向相机方向与设备自然方向不一致时,强制裁剪相机输出到相反方向。许多应用无法处理这种情况,否则会显示拉伸图像。

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

将属性标志 PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT 设置为 true

如何优化应用

请参阅OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

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

将属性标志 PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT 设置为 false

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

<property android:name="android.camera.PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT"
  android:value="true|false"/>

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

要应用强制内部前置摄像头裁剪的替换设置

adb shell am compat enable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

要移除移除内部前置摄像头裁剪的替换设置

adb shell am compat disable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION

阻止应用选择停用应用屏幕共享(请参阅媒体投影)。当应用滥用 createConfigForDefaultDisplay() API 强制全屏捕获并危及用户隐私(通过暴露通知内容,这些通知以全屏捕获而不是应用屏幕共享方式捕获,以及所有应用无论窗口模式如何)时,会实施此功能。

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

允许默认媒体投影行为(在 Android 14,API 级别 34 中实现,使用 createScreenCaptureIntent()),这使用户能够决定是共享全屏还是单个应用窗口,无论窗口模式如何。或者调用 createScreenCaptureIntent(MediaProjectionConfig),其中包含从调用 createConfigForUserChoice() 返回的 MediaProjectionConfig 参数。

如何优化应用

允许用户在媒体投影期间选择是共享整个设备显示屏还是应用窗口,这从 Android 14 开始是默认行为。

使您的应用可调整大小(resizeableActivity="true")以支持多窗口模式。

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

由于用户隐私的严重性,您的应用无法禁用或选择停用此替换。

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

无。

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

要应用替换,它会取消应用选择停用部分屏幕共享(即启用部分屏幕共享)

adb shell am compat enable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

要移除替换,它允许应用选择停用部分屏幕共享

adb shell am compat disable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

注意:命令仅暂时应用或移除替换设置。

OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS

启用分屏模式下未聚焦应用的假焦点发送。一些游戏引擎在绘制应用内容之前等待获取焦点;因此,假焦点有助于应用避免在恢复后仍保持黑屏状态,因为它们尚未获得焦点。

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

将属性标志 PROPERTY_COMPAT_ENABLE_FAKE_FOCUS 设置为 true

如何优化应用

如果您的应用能够很好地处理多种方向和配置更改,您可以避免此问题。请遵循大屏幕应用质量指南,使您的应用适应大屏幕。

如果您运行 Unity 游戏引擎,请升级到 2019.4.40 或更高版本,然后重新导出您的游戏。在Android 播放器设置中保持选中可调整大小窗口选项。

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

将属性标志 PROPERTY_COMPAT_ENABLE_FAKE_FOCUS 设置为 false

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

<property android:name="android.window.PROPERTY_COMPAT_ENABLE_FAKE_FOCUS"
  android:value="true|false"/>

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

要应用替换设置

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

要移除替换设置

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

注意:命令仅暂时应用或移除替换设置。

附加资源


  1. 虚拟设备所有者是管理虚拟设备的受信任或特权应用。虚拟设备所有者创建虚拟设备以渲染应用,然后将应用投影到远程设备,例如个人电脑、虚拟现实设备或车载信息娱乐系统。虚拟设备所有者位于本地设备上,例如手机。