Android NDK开发详解设备兼容性之大屏幕兼容模式二

按应用替换项

Android 提供可用于更改已配置的应用行为的替换项。例如，FORCE_RESIZE_APP 替换项指示系统绕过尺寸兼容模式，即使在应用清单中设置了 resizeableActivity=“false” 也是如此。

OEM 会在特定的大屏设备上按应用采用替换项。Pixel Tablet 和 Pixel Fold 会默认将一些替换项应用于各种应用。

注意：按应用替换项仅用于修正异常的应用行为或改善用户体验。应用可以选择停用某些替换项（请参阅下文的按应用替换项表格）。
您可以使用兼容性框架在启用或停用替换项的情况下测试您的应用（请参阅兼容性框架工具）。启用后，替换项会应用于整个应用。

您还可以使用 Android 调试桥 (adb) 启用或停用替换项，并确定哪些替换项应用于您的应用。

按如下所示启用或停用替换项：

adb shell am compat enable/disable <override name/id> <package>

对于 Pixel Tablet 和 Pixel Fold，检查哪些替换项应用于您的应用：

adb shell dumpsys platform_compat | grep <package name>

注意：如果 dumpsys platform_compat 针对 OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION 返回 true，系统不会强制旋转您的应用，如相机预览兼容性权宜解决方法中所述（见上文）。
如果 dumpsys platform_compat 针对 OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT 返回 false，系统不会对您的应用采取内部前置摄像头画面剪裁，如相机预览兼容性权宜解决方法中所述。

下表列出了可用的替换项，以及有关如何优化应用以免应用依赖于替换项的指南。您可以将属性标志添加到应用清单中，以停用某些替换项。

按应用替换项

类型	名称	ID	说明
尺寸可调整性	FORCE_RESIZE_APP	174042936	在发生配置更改时为应用绕过尺寸兼容模式。
FORCE_NON_RESIZE_APP	181136395	在发生配置更改时强制应用进入尺寸兼容模式。
宽高比	OVERRIDE_MIN_ASPECT_RATIO	174042980	必须启用 Gatekeeper 替换项才能应用任何其他宽高比替换项。
OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	如果启用（默认），则会将替换范围限定为仅限纵向的 activity。
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_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	当 activity 的屏幕方向未定义时，将屏幕方向替换为纵向。
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	当 activity 的屏幕方向未定义时，将屏幕方向替换为 nosensor（使用设备的自然屏幕方向）。
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	将仅限横向的应用旋转 180 度。
OVERRIDE_ANY_ORIENTATION	265464455	允许替换任何屏幕方向。
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	通过停用 OEM 忽略屏幕方向请求设置来防止进入信箱模式。
Sandbox API	NEVER_SANDBOX_DISPLAY_APIS	184838306	防止更改任何 Display API 的行为。
ALWAYS_SANDBOX_DISPLAY_APIS	185004937	强制应用中的 Display API 返回应用边界。Display API 会返回显示区域边界，但有时应用会假定 Display API 会返回应用边界，从而导致界面问题。
OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	强制应用中使用的 View API 返回应用边界。View API 会返回显示区域边界，但有时应用会假定 View API 会返回应用边界，从而导致界面问题。
相机兼容性	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	剪裁内部前置摄像头的图像缓冲区。如果此替换项被停用，系统会移除内部前置摄像头剪裁机制，并扩大相机预览的视野范围。在 Pixel Fold 上，当使用内部前置摄像头时，系统会默认剪裁所有相机应用的相机预览。
其他	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	防止应用在分屏模式下失去焦点时黑屏。应用会等待获得焦点，之后再绘制应用内容，这可能会导致应用冻结或黑屏。此替换项使 Android 能够向应用发送虚假焦点事件，从而指示应用重新开始绘制内容。

FORCE_RESIZE_APP

强制使采用此替换项的软件包可调整大小。不会更改应用是否可以进入多窗口模式，但使应用能够在屏幕大小调整时调整大小，而无需进入尺寸兼容模式。

注意：只有不可调整大小的应用才能设置宽高比限制。如需避免不可调整大小的应用进入尺寸兼容模式，请将以下 标记添加到应用清单：

<meta-data android:name="android.supports_size_changes" android:value="true" />

应用可以如何达成与替换项相同的结果
在应用清单中将 android:resizeableActivity 属性设置为 true 或将 android.supports_size_changes 元数据标志设置为 true（以便在将 android:resizeableActivity 设置为 false 的情况下支持调整大小，同时停用多窗口模式）。

如何优化应用
使用响应式/自适应布局，让应用能够适应所有显示大小和宽高比。请参阅支持不同的屏幕尺寸。

如何停用替换项
将属性标志 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

适用于会强制采用指定最小宽高比的所有处理的 Gatekeeper。

应用可以如何达成与替换项相同的结果
在 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 也处于启用状态时才会生效。

应用可以如何达成与替换项相同的结果
请参阅 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_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_UNDEFINED_ORIENTATION_TO_PORTRAIT

为软件包中的所有 activity 启用纵向屏幕方向。除非已启用 OVERRIDE_ANY_ORIENTATION，否则只有当 activity 未指定其他固定屏幕方向时，系统才会使用此替换项。

应用可以如何达成与替换项相同的结果
设置 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_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 未指定其他固定屏幕方向时，系统才会使用此替换项。

应用可以如何达成与替换项相同的结果
设置 activity:screenOrientation 清单属性，或使用 Activity#setRequestedOrientation API。

如何优化应用
请参见OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_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 未指定其他固定屏幕方向时，系统才会使用此替换项。

应用可以如何达成与替换项相同的结果
设置 activity:screenOrientation 清单属性，或使用 Activity#setRequestedOrientation API。

如何优化应用
请参见OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

如需移除此替换项，请使用以下命令：

adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <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。

如何优化应用
请参见OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_ORIENTATION_ONLY_FOR_CAMERA

将 OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT、OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR 和 OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE 替换项限制为仅在相机连接处于有效状态时生效。

应用可以如何达成与替换项相同的结果
设置 activity:screenOrientation 清单属性，或使用 Activity#setRequestedOrientation API。

如何优化应用
请参见OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_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
已针对显示屏启用 OEM 忽略屏幕方向请求设置
显示屏的自然屏幕方向为横向
应用可以如何达成与替换项相同的结果
不适用。此问题应该在应用逻辑中解决。

如何优化应用
请参见OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
将属性标志 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_UNDEFINED_ORIENTATION_TO_PORTRAIT。

如何停用替换项
无法选择停用。如果应用与已启用 OEM 忽略屏幕方向请求设置的设备不兼容，停用此替换项可能会有危险。如需停用此替换项，请与 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 可调整大小。

如何优化应用
声明完全可调整大小的应用绝不应该依赖显示大小来确定界面元素的位置。请将您的应用迁移到提供 WindowMetrics 的最新 API。如果您使用的是 Jetpack Compose，您可以利用 WindowSizeClass API，根据应用在当前显示屏上可用的屏幕区域大小来绘制界面。请参阅支持不同的屏幕尺寸。

如何停用替换项
无法选择停用。从已废弃的 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 不可调整大小。

如何优化应用
声明完全可调整大小的应用绝不应该依赖显示大小来确定界面元素的位置。将您的应用从已废弃的 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

针对 activity 边界，强制使软件包采用以下 View API 沙盒机制：

getWindowVisibleDisplayFrame()
getLocationOnScreen()
应用可以如何达成与替换项相同的结果
使用会提供应用窗口边界及相对于应用窗口的偏移量（而不是设备显示屏边界及相对于设备显示屏的偏移量）的 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。

如何优化应用
请勿依赖缓存的摄像头传感器方向或设备信息。有关相机兼容性指南，请参阅相机取景器简介和在相机应用中支持可调整大小的 Surface。

如何停用替换项
将属性标志 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。

如何优化应用
请勿依赖缓存的摄像头传感器方向或设备信息。有关相机兼容性指南，请参阅相机取景器简介和在相机应用中支持可调整大小的 Surface。

如何停用替换项
将属性标志 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。

如何优化应用
请勿依赖缓存的摄像头传感器方向或设备信息。有关相机兼容性指南，请参阅相机取景器简介和在相机应用中支持可调整大小的 Surface。

如何停用替换项
将属性标志 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。

如何优化应用
请勿依赖缓存的摄像头传感器方向或设备信息。有关相机兼容性指南，请参阅相机取景器简介和在相机应用中支持可调整大小的 Surface。

如何停用替换项
将属性标志 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_ENABLE_COMPAT_FAKE_FOCUS

分屏模式下允许针对未获焦点的应用发送虚假焦点。有些游戏引擎会等待获得焦点，然后再绘制应用内容；因此，虚假焦点有助于应用在恢复运行但尚未获得焦点时避免保持黑屏状态。

应用可以如何达成与替换项相同的结果
将属性标志 PROPERTY_COMPAT_ENABLE_FAKE_FOCUS 设置为 true。

如何优化应用
如果您的应用会妥善处理多个屏幕方向和配置更改，您可以避免此问题。请遵循大屏设备应用质量指南，让您的应用支持大屏设备。

如果您运行的是 Unity 游戏引擎，请升级到版本 2019.4.40 或更高版本，然后重新导出游戏。在 Android Player 设置中使 Resizable Window 选项保持选中状态。

如何停用替换项
将属性标志 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>

注意：这些命令只能暂时应用或移除此替换项。

其他资源

大屏设备应用质量指南
核心应用质量指南
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。

最后更新时间 (UTC)：2023-11-24。