Android 会为声明了屏幕方向或 可调整性限制。兼容模式可确保在 Android 设备上 大屏设备和可折叠翻盖手机,但易用性不太理想。
按应用替换项可让设备制造商更改 旨在改善用户体验或防止应用中断的应用行为 特定设备
参照设备
由于存在异常,以下设备可能需要按应用替换项 未得到应用良好支持的配置或配置:
- 平板电脑:某些平板电脑(例如 Pixel Tablet)的自然屏幕方向
是横向的当设备处于自然屏幕方向时
Display#getRotation()
退货Surface.ROTATION_0
。如果应用假定ROTATION_0
为纵向, 应用布局和相机预览可能与设备显示屏不匹配。 - 横向可折叠设备:某些可折叠设备(例如 Pixel Fold)采用 折叠时为纵向,但展开时为横向。 如果应用假设展开状态下的屏幕方向为纵向,应用就会闪烁 可能会出现循环或布局问题。
- 可折叠的翻盖手机:展开的翻盖手机通常处于竖屏模式 屏幕方向。但是,在折叠时,手机通常只有一个小显示屏 横向模式。应用必须识别和适应不同 显示方向。
常见兼容性问题
应用之所以会发生兼容性问题,最常见的原因是应用的屏幕方向问题 限制、尺寸可调整性和宽高比限制、错误处理 相机预览方向和滥用的 API。
信箱模式
信箱模式会将应用放置在屏幕中央,在大屏幕上, 以方便访问哑光纸(纯色条) 或模糊的壁纸)填满侧面或顶部未使用的显示区域, 底部
大屏设备上经常会出现信箱模式,因为 设备显示屏的宽高比通常与标准显示屏的宽高比不同 手机,大多数应用都是针对这类手机而设计的。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/letterboxing.png?authuser=5&hl=lt)
图 1. 仅限纵向的应用在横屏平板电脑和可折叠设备上会进入信箱模式。
问题
应用已修复,因此仅支持部分显示配置 屏幕方向、固定宽高比或不可调整大小。
用于控制应用屏幕方向和尺寸可调整性的配置设置包括 以下:
screenOrientation
:为 一个应用。应用还可以使用Activity#setRequestedOrientation()
。resizeableActivity
:指示系统是否可以 调整应用大小,以适应不同尺寸的窗口。在 Android 11(API 级别)上 30) 及更低版本,指定应用是否支持多窗口模式。已开启 Android 12(API 级别 31)及更高版本,指定应用是否支持 小屏设备上的多窗口模式 窗口大小类别)。在 Android 12 及更高版本中,应用 支持大屏设备(中等窗口或较大窗口)上的多窗口模式 size 类别),则不受此设置的影响。maxAspectRatio
:指定最大宽高比 。只有resizeableActivity
设置为false
的应用才能 设置maxAspectRatio
。minAspectRatio
:指定最小宽高比 。只有resizeableActivity
设置为false
的应用才能 设置minAspectRatio
。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/letterboxing_issue.png?authuser=5&hl=lt)
仅限纵向的应用在横屏设备上无法使用。
优化
应用应支持所有设备和多窗口模式显示屏 屏幕方向和尺寸移除所有屏幕方向和固定宽高比 应用布局和应用清单文件中的限制。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/letterboxing_optimization.png?authuser=5&hl=lt)
应用支持所有设备屏幕方向。
兼容性问题权宜解决方法
如果具有固定屏幕方向或固定宽高比的应用在 应用不直接支持窗口大小或方向,Android 使应用进入信箱模式,以保持连续性。
从 Android 12(API 级别 31)开始,一直到 Android 12L(API 级别 32), 该平台会对进入信箱模式的应用应用各种增强功能。设备 制造商会实现界面增强功能您无需执行任何其他操作 以便从改进中受益。
Android 12(API 级别 31)引入了以下提升美感的增强功能, 可由设备制造商配置:
- 圆角:让应用窗口的四角看起来更美观好看。
- 系统栏透明度:状态栏和导航栏:叠加在 是半透明的,因此,在 信箱模式背景。
- 可配置的宽高比:可调整应用的宽高比 来改善应用的外观。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/enhanced_letterboxing.png?authuser=5&hl=lt)
图 2. 采用界面增强功能的应用在进入信箱模式后的显示效果。
Android 12L(API 级别 32)增加了以下功能改进:
放置位置可配置:在大屏设备上,设备制造商可以 将应用放置在显示屏的左侧或右侧 和互动
重新设计的重启按钮:设备制造商可以指定重启按钮 用于尺寸兼容模式新外观的按钮 以便更好地被用户识别
Android 13(API 级别 33)添加了一个用户指导对话框,用于说明如何定位 显示进入信箱模式的应用,或在分屏模式下包含信箱模式:
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/enhanced_letterboxing_user_dialog.png?authuser=5&hl=lt)
图 3. 包含用户指导对话框的进入信箱模式的应用。
尺寸兼容模式
尺寸兼容模式是指包含重启控件的信箱模式。通过 控件可让用户重启应用并重新绘制显示屏。Android 调用次数 尺寸兼容模式。当 activity 移动到与其自身不兼容的显示容器 因此系统可能会重新缩放应用,以填满设备显示屏 至少一个维度。
可能触发尺寸兼容模式的设备配置更改包括:
- 设备旋转
- 可折叠设备的折叠或展开
- 在全屏和分屏显示模式之间切换
问题
尺寸兼容模式通常适用于 屏幕方向或宽高比并配置为(或由系统确定) 不可调整大小。
您的应用被视为可调整大小,不会按尺寸放置 兼容模式 - 如果它符合以下任一条件:
- 可通过
resizeableActivity="true"
调整大小 - 支持画中画 (PIP) 模式
- 是嵌入式的
- 已应用
FORCE_RESIZE_APP
按应用替换项 设备制造商(由应用设置的属性会被忽略)
如果您的应用不满足上述任一条件,则会被视为 可调整大小,并可置于尺寸兼容模式下。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/size_compatibility_mode_issue.gif?authuser=5&hl=lt)
在多窗口模式下,不可调整大小的应用会崩溃。
优化
应用应支持所有显示大小。通过设置
<activity>
的 android:resizeableActivity
属性
或<application>
元素至true
应用清单中。为您的应用设计响应式/自适应布局。有关
请参阅
支持不同的屏幕尺寸和支持
多窗口模式
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/size_compatibility_mode_optimization.gif?authuser=5&hl=lt)
应用适用于所有窗口大小。
兼容性问题权宜解决方法
当系统确定 可以改善进入信箱模式的应用的显示效果,方法是重新缩放应用 在至少一个维度显示窗口。系统会显示重启控件 这会重新创建应用进程,重新创建 activity,并重新绘制 。另请参阅进程和线程概览。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/size_compatibility_mode_workaround.gif?authuser=5&hl=lt)
仅限纵向的应用在横屏状态下进入信箱模式,并被重启控件重新缩放。
闪烁循环
如果某个应用仅支持部分显示屏方向,它可能会反复 在发生配置更改时请求新的屏幕方向,从而创建一个 导致显示屏闪烁或应用无休止地旋转的无限循环。
问题
在 Android 12(API 级别 31)及更高版本中,设备制造商可以
其设备会忽略应用指定的屏幕方向限制,
强制实施兼容模式例如,可折叠设备可以忽略
活动的android:screenOrientation="portrait"
activity 在设备的横向平板电脑尺寸、
内屏。
如果忽略某个应用的屏幕方向限制,此应用可以通过编程方式
通过调用
Activity#setRequestedOrientation()
。通话
在应用未处理配置更改时触发应用重启(请参阅
处理配置更改)。在
应用的屏幕方向限制将再次被忽略,并且应用会不断重复
调用 setRequestedOrientation()
,该调用会触发应用重启,以及
以此类推。
您可能会遇到这种情况的另一种方式是
自然屏幕方向(通常
为横向(即,调用
Display#getRotation()
返回
Surface.ROTATION_0
(当设备采用横向模式时)
比率)。过去,应用假定 Display.getRotation() =
Surface.ROTATION_0
表示设备处于竖屏模式,但实际上并非如此
始终如此,例如,在某些可折叠设备的内屏上,以及
在某些平板电脑上。
在可折叠设备内屏上,横屏模式的应用可能会检查
屏幕旋转,收到的值为 ROTATION_0
,采用自然屏幕方向
并调用
setRequestedOrientation(
ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
)
重新配置应用布局。应用重启后(横屏模式)
屏幕方向),它可能会再次检查屏幕旋转情况,并收到
ROTATION_0
,拨打电话
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT)
和
继续进行无限循环
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/flickering_loops_issue.gif?authuser=5&hl=lt)
仅限横向的应用在竖屏上重复调用 Activity#setRequestedOrientation()
。
优化
应用不应执行以下操作:
- 使用
Activity#setRequestedOrientation()
中的 activityonCreate()
方法,因为屏幕方向请求可以是 由未处理的配置更改意外触发 - 假定设备的自然屏幕方向 (
ROTATION_0
) 为纵向 - 根据与当前窗口大小无关的信号设置屏幕方向,例如
Display#getRotation()
,FoldingFeature
或已废弃的 API。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/flickering_loops_optimization.gif?authuser=5&hl=lt)
应用处理配置更改,没有屏幕方向限制,因此不会进入闪烁循环。
兼容性问题权宜解决方法
在以下代码中 Android 会忽略对 Activity#setRequestedOrientation()
的调用
情况:
该 Activity 已通过之前对方法的调用或 已启用相机兼容性强制旋转处理(请参阅相机 “预览版”。
设备制造商可以将此行为应用于具有
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
。activity 在一秒内发出了两个以上的屏幕方向请求, 表示发生了循环。在循环中的两个请求中,Android 使用 最大程度地扩大应用显示区域的尺寸。
设备制造商可以将此行为应用于具有
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
。
相机预览
相机应用的相机预览(或取景器)可能未对齐或失真 平板电脑、笔记本电脑和可折叠设备的屏幕。
问题
Android 兼容性定义文档中规定, 摄像头图像传感器 "必须朝向正确方向,以便摄像头的长度方向 与屏幕的长度方向对齐。”
应用通常假定设备的屏幕方向和摄像头传感器方向 纵向 - 在标准手机上是一种合理的假设。但是 平板电脑和笔记本电脑的自然屏幕方向, 横向模式。此外,可折叠设备等新外形规格的设备可能具有多种 以及多个不同屏幕方向的摄像头传感器。
以应用不需要的摄像头方向启动 activity 或 在不同摄像头或设备屏幕(对于可折叠设备)之间切换可能会导致 未对齐或扭曲的相机预览。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/camera_preview_issue.png?authuser=5&hl=lt)
在大屏可折叠设备上,相机预览未对齐且扭曲。
优化
相机应用必须正确识别和管理设备的屏幕方向和摄像头 传感器方向,以显示正确对齐和缩放的相机预览。 应用必须计算设备旋转角度、传感器旋转角度以及屏幕或窗口 然后对相机预览应用结果。如需详细了解 指南,请参阅相机预览和相机简介 取景器。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/camera_preview_optimization.png?authuser=5&hl=lt)
在设备横屏和竖屏模式下正确对齐和缩放的相机预览。
兼容性问题权宜解决方法
当 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 来获取常规显示指标。
结果是在应用窗口后重新定位界面元素时计算错误
调整事件大小,导致布局问题。
已废弃和常遭滥用的 Display API:
如需了解详情,请参阅 支持多窗口模式。
遭到滥用的 View API:
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/misused_APIs_issue.png?authuser=5&hl=lt)
已废弃的 API 错误地计算应用边界。部分应用内容超出了屏幕边界。
优化
从不依赖实际显示大小来确定界面元素位置。迁移您的
应用传递给基于 WindowMetrics
的 API,包括:
WindowManager
API:
平台:
Jetpack:
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/misused_APIs_optimization.png?authuser=5&hl=lt)
API 正确计算应用窗口指标。
兼容性问题权宜解决方法
两个替换项会调整已废弃的 Display
API 和被滥用的 View
API,
返回应用边界:
Display
的ALWAYS_SANDBOX_DISPLAY_APIS
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 可以是 trampoline(启动另一个 activity 然后消失的 activity);和 因此,系统将无法确定 启动透明权限对话框 activity。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/transparent_activities_issue.png?authuser=5&hl=lt)
对话框定位错误,因为 activity 是从 trampoline 启动的。
优化
透明 activity 会继承最顶层的不透明 activity 的约束条件 它们在任务的 activity 堆栈中位于其下方的 activity 之间。不透明 activity 必须是 适用于透明 activity 的整个生命周期,即从 activity 开始, 从创造到毁灭。因此,请勿在 trampoline activity
如果 trampoline activity 启动权限请求,用户可能不会 可以看到权限对话框,因为 trampoline activity 在用户有机会响应对话框之前就销毁了,并且 对话框 activity 的尺寸和位置 错误。
应用应始终从 在用户做出权限决定之前显示。
圆角
activity 由于具有指定背景的样式,因此可以是透明的 或者由于 activity 的内容未填满可用的 展示空间如果透明 activity 填满了可用的显示空间, 配置为 由设备制造商执行相关操作但是,如果某个透明活动(例如 权限对话框)未填满可用空间,则由您自行决定 是否应用圆角。
权限对话框未填满可用的显示空间,因为对话框 布局通常使用 LayoutParams.WRAP_CONTENT,而不是 LayoutParams.MATCH_PARENT。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/transparent_activities_optimization.png?authuser=5&hl=lt)
圆角正确位于可见启动 activity 上方的对话框。
兼容性问题权宜解决方法
使启动对话框 activity 的 activity 保持可见状态,直到用户执行 已回复此对话框。
系统会确保透明 activity 继承所有约束条件 activity 堆栈中透明 activity 下方的第一个不透明 activity; 包括与以下方面相关的限制条件:
- 尺寸兼容模式
- 屏幕方向
- 宽高比
Unity 游戏
在 Android 设备上,Unity 游戏可以在全屏模式或多窗口模式下运行。不过, 许多 Unity 游戏在应用被放置在以下位置时,会失去焦点,并停止绘制内容 多窗口模式
问题
Unity 添加了一个 Resizable Window
。
选项,以在 Android 上支持多窗口模式。不过,
初始实现在
多窗口模式
UnityPlayer 在应用失去焦点时暂停播放。播放器
黑屏或游戏的最后一个冻结帧。仅当
用户点按了屏幕许多使用 Unity 引擎的应用都会面临这个问题,
在多窗口模式下渲染为黑色窗口。
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/unity_games_issue.gif?authuser=5&hl=lt)
在多窗口模式下,游戏失去焦点,并渲染为黑色窗口。
优化
将 Unity 升级到 2019.4.40 或更高版本,然后重新导出游戏。将
已在以下字段中选中“Resizable Window
”选项:
Android 播放器设置,否则
游戏会在失去焦点时暂停,即使游戏在
多窗口模式
![](https://developer.android.google.cn/static/images/guide/practices/compatibility-mode/unity_games_optimization.gif?authuser=5&hl=lt)
在多窗口模式下,让游戏渲染内容在失去焦点时也能正常运行。
兼容性问题权宜解决方法
设备制造商可以将
OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS
按应用替换项,以便在
多窗口模式此替换项使 activity 能够重新绘制内容
不要被涂黑
测试应用是否存在兼容性问题
如需测试您的应用并了解它在不同外形规格上的行为方式,请采取以下做法: 充分利用以下资源:
- 设备串流:在正式版设备(包括 参考设备),请参阅 Android 设备串流功能,由 Firebase 提供支持
- Android Studio Hedgehog 中的模拟器:如需了解如何创建 参考设备的模拟器,请参阅 创建和管理虚拟设备
- 可调整大小的 Android Studio 模拟器:如需了解如何访问 请参阅在 Android 模拟器上运行应用
为信箱模式
确认是否每个 activity 都可以使用应用可用的所有显示空间。首先,在测试文件夹中声明以下代码:
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(); }
然后,运行测试以断言该行为,并确保目标 activity 未 信箱模式:
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(); }); } }
理想情况下,应只运行此类测试,直到测试通过并声明应用 activity 会占用应用可用的整个显示空间。测试应用 ,以确保行为一致。
按应用替换项
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>
全屏选项已从 设备设置。用户无法将全屏替换项应用于 。
将此属性设置为
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 | 必须启用 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_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 | 通过停用设备制造商忽略屏幕方向请求设置来防止进入信箱模式。 | |
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 | 剪裁内部前置摄像头的图像缓冲区。如果此替换项被停用,系统会移除内部前置摄像头画面剪裁,并扩大相机预览的视野范围。默认情况下,在某些可折叠设备(请参阅参照设备)上,使用内部前置摄像头时,系统会剪裁所有相机应用的相机预览。 | |
其他 | 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
用于强制采用指定最小宽高比的所有替换项的 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_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
。在小屏设备上,支持调整应用大小,同时停用多窗口模式 模式,
android:resizeableActivity=false
设置 将android.supports_size_changes
元数据标志设置为true
。不要设置minAspectRatio
和maxAspectRatio
。
如何优化应用
让您的应用支持所有屏幕方向;不设置 screenOrientation
并在应用清单中指定该规范支持应用尺寸调整
多窗口模式以及所有屏幕宽高比
android:resizeableActivity
属性设为 true
。请参阅
支持不同的屏幕尺寸。
如何停用替换项
用于调整替换项的属性标志
用于测试替换项的 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 未指定其他固定屏幕方向时使用。
应用可以如何达成与替换项相同的结果
如何优化应用
如何停用替换项
用于调整替换项的属性标志
用于测试替换项的 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
为 软件包。除非 OVERRIDE_ANY_ORIENTATION 为 则仅当您未设置任何其他固定屏幕方向时,系统才会使用此替换项 由 activity 指定。
应用可以如何达成与替换项相同的结果
如何优化应用
如何停用替换项
用于调整替换项的属性标志
用于测试替换项的 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 指定。
应用可以如何达成与替换项相同的结果
如何优化应用
如何停用替换项
用于调整替换项的属性标志
用于测试替换项的 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_PORTRAIT、 OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR、 和 OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE 覆盖仅在相机连接处于活动状态时生效。
应用可以如何达成与替换项相同的结果
如何优化应用
如何停用替换项
用于调整替换项的属性标志
用于测试替换项的 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
未启用 - 已针对以下设备启用设备制造商忽略屏幕方向请求设置: 显示屏
- 显示屏的自然屏幕方向为横向
应用可以如何达成与替换项相同的结果
不适用。此问题应该在应用逻辑中解决。
如何优化应用
如何停用替换项
设置属性标志
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
。
如何优化应用
如何停用替换项
设置属性标志
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#setRequestedOrientation()
超过两次
如果 activity 未针对固定屏幕方向进行信箱模式,则为 1 秒。
应用可以如何达成与替换项相同的结果
不适用。此问题应该在应用逻辑中解决。
如何优化应用
如何停用替换项
设置属性标志
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
从可启用的忽略屏幕方向请求行为中排除软件包 显示区域或整个显示区域。
应用可以如何达成与替换项相同的结果
不适用。此问题应该在应用逻辑中解决。
如何优化应用
如何停用替换项
无法选择停用。如果应用不兼容,停用此替换项可能会有危险 设备制造商忽略屏幕方向请求 设置。与 Android 开发者联系 Relations 来停用替换项。
用于调整替换项的属性标志
此替换项没有属性标志。
用于测试替换项的 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
强制软件包从不应用 Display
API 沙盒
(针对进入信箱模式或尺寸兼容模式的 activity)。Display
API
继续提供显示区域边界。
应用可以如何达成与替换项相同的结果
通过设置
将 android:resizeableActivity
清单属性设为 true
或者将 android.supports_size_changes
元数据标志设为 true
。
如何优化应用
声明完全可调整大小的应用绝不应依赖显示大小
放置界面元素将您的应用迁移到
提供 WindowMetrics
。如果您使用的是 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
。
如何优化应用
声明完全可调整大小的应用绝不应依赖显示大小来实现
定位界面元素将您的应用从已弃用的 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 沙盒机制:
应用可以如何达成与替换项相同的结果
使用提供边界值的 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
。
如何优化应用
请参阅 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()
执行 activity 刷新
→ onPause()
→ onResume()
循环,而非 onResume()
→
onStop()
→ onResume()
(在相机兼容性强制旋转后)。
应用可以如何达成与替换项相同的结果
设置属性标志
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)
参数中返回MediaProjectionConfig
参数
对 createConfigForUserChoice()
的调用。
如何优化应用
允许用户选择是共享设备的所有显示屏还是应用 窗口,从 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 或更高版本,
重新导出您的游戏保留 Resizable Window
选项
已在 Android Player 中选中
设置。
如何停用替换项
设置属性标志
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>
注意:这些命令只能暂时应用或移除此替换项。