小米大屏设备适配说明2-APP开发

小米大屏设备适配说明2

2.3 不同类型应用适配建议

针对不同行业，不同类型应用，我们推荐以下五种布局方案：多列布局，Tab拉伸布局，分栏布局，左右布局和横屏拉宽。

适配方式	应用所属行业
多列布局	金融理财，居家生活，时尚购物，影音视听，医疗健康，学习教育
Tab拉伸布局	新闻资讯，图书阅读，摄影摄像，短视频
分栏布局	聊天社交，效率办公
左右布局	实用工具，音乐，时钟，天气，体育运动
横屏拉宽	游戏，旅游交通

针对以上适配方式，具体描述和详细示意图如下（左图为APP在手机上的效果，中图为APP在折叠屏内屏上的效果，右图为APP在大屏设备上的效果）

A.多列布局

在应用首页，此类适配下顶部和底部的Tab拉伸到适合大屏设备页面的大小，同时首页主要功能键/APP推荐位置数量增加。

上图为应用商店类APP手机&大屏设备适配示意

上图为视频类APP手机&大屏设备适配示意

B.Tab拉伸

Tab拉伸适配下，页面主要内容不变，页面两侧加上与主要页面背景色同色/相近的背景，同时顶部和底部的Tab拉伸到适合大屏设备页面的大小。顶部按键数量相比于手机可有相应提升。

上图为新闻资讯类APP手机&大屏设备适配示意

上图为短视频类APP手机&大屏设备适配示意

C.分栏布局

分栏适配下，大屏设备上的页面分栏模式与电脑端的IM社交应用保持一致。

上图为社交IM类APP手机&大屏设备适配示意

D.左右布局

左右布局下，顶部和底部的Tab拉伸到适合大屏设备页面的大小，内部页面左右分列，左侧展示主要的文字性内容，右侧展示相应的图片，视频等。

上图为音乐类APP手机&大屏设备适配示意

E.横屏拉宽

此类适配下，APP界面在大屏设备内横屏时，横向铺满屏幕

3、通用开发适配指南

3.1 屏幕尺寸兼容性

应用resizeable 能力支持

运行 Android 的设备多种多样，尤其是当前已出现或未来可能出现的折叠屏设备，它们有着不同的屏幕尺寸和像素密度，而且在折叠屏设备从展开到折叠的切换过程中，同一个设备可能出现多种屏幕尺寸的使用状态。您在做app设计和开发的时候应该考虑支持不同屏幕尺寸和像素密度，以确保界面能够在各类屏幕上美观地呈现。

折叠屏之所以需要适配，是因为我们的应用有可能在运行的过程中，所在的屏幕尺寸发生了变化，这种情况对现有项目多少都会产生一些问题。

所以折叠屏适配的本质是：

当应用运行时，屏幕的尺寸、密度或比例发生了变化，应用能够继续在变化后的屏幕上正常显示和正常运行

允许改变应用尺寸

要适配折叠屏，首先是要让应用支持动态改变尺寸，我们需要根据应用面向的API Level （targetSdkVersion）进行支持resizeable能力在 manifest 中的 Application 或对应的 Activity 下声明：

如果应用程序面向API Level 24以上（targetSdkVersion>=24），系统将默认应用支持resizeable能力。
如果应用程序面向API Level 24以下（targetSdkVersion< 24），需要应用在manifest中显式的声明android:resizeableActivity=true，才可以支持resizeable能力。

android: resizeableActivity = ["true" | "false"]

备注：虽然安卓提供了申请受限屏幕能力，但强烈建议您为应用设计resizeable能力，因为一旦您声明了受限屏幕比例（最大或最小）这意味着，当您的app运行在一个屏幕比例超出了您声明的范围，您的应用程序在屏幕上将出现黑边等现象。

详细信息请参阅Android开发者指南

3.2 横竖屏状态获取

需要通过判断AppWindow的宽高比判断是横屏还是竖屏。

（1）宽:高 >= 1为横屏

（2）宽:高 < 1为竖屏

传递给应用的Configuration中的orientation会标识当前是横屏还是竖屏

（1）Configuration.ORIENTATION_LANDSCAPE为横屏

（2）Configuration.ORIENTATION_PORTRAIT为竖屏

3.3 横屏适配情况标记

应用主动适配大屏设备横屏，采用适配全屏的多列布局、Tab拉伸、分栏布局、左右布局、横屏拉宽等方式，需要在AndroidMainfest.xml文件设置标记。设置了此标记，横屏下会优先使用应用自己适配的横屏布局，而不是进入平行窗口下的横屏模式。

<!-- support landscape for large screen(PAD) -->
        <meta-data
            android:name="LandscapeForPad"
            android:value="true" />

3.4 折叠屏连续性支持

折叠连续性的定义：应用在可折叠设备上运行时，当屏幕发生折叠/展开动作，处于前台的应用会从一个屏幕转换到另一个屏幕，为提供出色的用户体验，确保当前应用能在转换后能连续无缝、正常地运行，应用应在同一位置以相同状态恢复，并且依然保持可用良好的UI布局。

三方应用需在 AndroidManifest.xml 文件的 application层级中添加 android.supports_size_changes或者

miui.supportAppContinuity

属性，以便声明应用支持连续性：

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

<application>      
    <meta-data
        android:name="miui.supportAppContinuity"
        android:value="true" />
</application>

Activity的配置应该尽量支持resizeableActivity。应用需要在 AndroidManifest.xml 文件的 application 或者 actvivity 标签中添加 resizeableActivity=true 的属性。若应用不支持多窗口（例如小窗、分屏等）而声明了resizeableActivity=false，则在折叠屏折叠/展开场景中，可能出现UI布局问题、或者进入到原生的安卓兼容模式（SizeCompatMode）。

<application
    android:resizeableActivity="true">
 
    <activity
          android:resizeableActivity="true" />
</application>

若应用的 targetSDK 为 24 或以上，即便不设置 resizeableActivity 属性，其默认值也为 true。

在设备发生屏幕切换后，应用应能妥善地保存界面状态或者支持配置变更。

保存界面状态

在应用Activity 被系统销毁重走生命周期时，应用需要及时保存和恢复 Activity 的界面状态，应用可以在 onSaveInstanceState 和 onRestoreInstanceState 方法中保存和恢复数据状态：

@Override
public void onSaveInstanceState(@NonNull Bundle outState, @NonNull PersistableBundle outPersistentState) { 
   super.onSaveInstanceState(outState, outPersistentState);
} 

@Override
protected void onRestoreInstanceState(@NonNull Bundle savedInstanceState) {    
   super.onRestoreInstanceState(savedInstanceState);
}

支持配置变更

应用也可以支持配置变更，保持 Activity 不重走生命周期，这时需要应用在 AndroidManifest.xml 中配置如下 configChanges 属性：

<activity android:configChanges="screenSize|smallestScreenSize|screenLayout" />

添加 android:configChanges 后，Activity 或者 Fragment 就会收到 onConfigurationChanged() 的回调，此方法会收到传递的Configuration对象，从而指定新设备配置。通过读取

Configuration中的字段确定新配置，然后通过更新界面所用资源进行适当的更改。调用此方法时，Activity 的Resources对象会相应地进行更新，并根据新配置返回资源，以便您在系统不重启 Activity 的情况下轻松重置界面元素。

代码示例：

@Override
public void onConfigurationChanged(@NonNull Configuration newConfig) {         
   super.onConfigurationChanged(newConfig); 
   Toast.makeText(this, "onConfigurationChanged newWidth="
   + newConfig.screenWidthDp  + ", newHeight=" 
   + newConfig.screenHeightDp, Toast.LENGTH_SHORT).show();
}

MIUI针对折叠屏设备新增了针对app侧的wm_on_configuration_changed_called回调EventLog，结合系统侧configuration_changed回调EventLog日志和”Config changes”调用的SystemLog，可以方便您快速定位、排查与onConfigurationChanged回调有关的问题。

Log示例：

// 系统侧触发configurationChanged事件日志（EventLog）
07-20 12:43:31.521 1000 2677 2778 I configuration_changed: 536874240
// App侧触发configurationChanged回调事件日志（EventLog），4个参数分别代表userId、目标Activity、Configuration、耗时。
07-20 12:43:31.701 10086 5585 5585 I wm_on_configuration_changed_called: [0,com.miui.home.launcher.Launcher,{1.0 ?mcc?mnc [zh_CN] ldltr sw696dp w696dp h738dp 440dpi lrg hdr widecg port ?pc finger -keyb/v/h -nav/h winConfig={ mBounds=Rect(0, 0 - 1914, 2160) mAppBounds=Rect(0, 0 - 1914, 2116) mMaxBounds=Rect(0, 0 - 1914, 2160) mWindowingMode=fullscreen mDisplayWindowingMode=fullscreen mActivityType=home mAlwaysOnTop=undefined mRotation=ROTATION_0 mInSplitScreen=false} as.2 s.24 fontWeightAdjustment=0 themeChanged=0 themeChangedFlags=0 extraData = Bundle[{}] dt/m/d},96]
// Config changes关键字SystemLog
2022-07-14 09:54:11.891 2485-2638/system_process I/ActivityTaskManager: Config changes=20000d00 {1.0 ?mcc?mnc [zh_CN] ldltr sw696dp w696dp h738dp 440dpi lrg hdr widecg port ?pc finger -keyb/v/h -nav/h winConfig={ mBounds=Rect(0, 0 - 1914, 2160) mAppBounds=Rect(0, 0 - 1914, 2116) mMaxBounds=Rect(0, 0 - 1914, 2160) mWindowingMode=fullscreen mDisplayWindowingMode=fullscreen mActivityType=undefined mAlwaysOnTop=undefined mRotation=ROTATION_0 mInSplitScreen=false} as.2 s.8214 fontWeightAdjustment=0 themeChanged=0 themeChangedFlags=0 extraData = Bundle[{}] dt/s/d}

适配调试命令

在对三方应用折叠屏连续性支持情况测试的过程中，我们发现部分应用虽自行处置了配置变更，在AndroidManifest.xml中配置了screenSize|smallestScreenSize|screenLayout等configChanges属性，并回调onConfigurationChanged方法对屏幕做了适配，Activity不会重建，也不会重走生命周期。但应用的Activity仍然存在很多控件显示问题。

为了带给用户良好的使用体验，我们在系统中忽略了这部分app的configChanges属性配置，强制让应用的Activity执行重建，并重走生命周期，以达到界面完美显示的效果，我们将这种行为称为relaunch。

为了方便您在我们的设备上进行适配，我们提供了如下命令帮助您屏蔽上述的relaunch行为。

屏蔽relaunch行为，是我们在经过充分测试评估后，认为您的应用即使执行relaunch，也无法达到连续性适配测试标准，甚至因relaunch重走生命周期，导致折叠展开后亮屏变慢、回到桌面、闪退、ANR等问题，因此屏蔽relaunch行为，旨在屏蔽上述亮屏变慢、回到桌面、闪退、ANR等一系列连续性、稳定性问题。

如果您希望通过relaunch重建Activity生命周期来适配折叠屏连续性，您需要关注上述的连续性、稳定性问题，避免在重建Activity生命周期中执行耗时操作，影响折叠展开时的应用性能、亮屏速率等，并避免在onDestroy里调用finish，以免折叠展开后回到桌面。

通过如下命令，您的应用在没有配置screenSize|smallestScreenSize|screenLayout等configChanges属性的情况下，折叠展开操作时仍能正常回调onConfigurationChanged方法，Activity不会重建，生命周期不会重走，但与此同时，在折叠屏折叠展开操作时可能会有通知提醒您应用显示存在异常，需要重启。您无需理会上述系统通知，它不会对您的适配造成任何影响。

adb shell wm dump -setForceDisplayCompatMode 应用包名 blocklist

上述命令会导致您的应用无法执行relaunch重建，即使您的应用没有配置screenSize|smallestScreenSize|screenLayout等configChanges属性，但您的应用仍能正常回调onConfigurationChanged方法。为了您的应用能自行处置screenSize|smallestScreenSize|screenLayout等configChanges属性，您可以直接使用下面的命令，该命令会将您的应用恢复到Android 原生的处置配置变更的流程，便于您进行适配工作。与此同时，该命令会帮助您屏蔽掉重启通知，以免对您的适配工作造成打扰。

adb shell wm dump -setForceDisplayCompatMode 应用包名 allowlist

如果您希望恢复relaunch状态，可执行如下命令（尽管我们不建议您这么做，仍然希望您能通过configChanges进行适配工作）：

adb shell wm dump -setForceDisplayCompatMode 应用包名 relaunchlist

请注意：以上命令行为不会在设备中持久化保存，在设备重启后就会失效。如有需要，您可再次执行上述命令。此外，执行命令后，您需要将您的应用从最近任务移除后重新启动，来保证命令生效。

如您已完成应用连续性适配，可以联系我们，在测试您的应用达到连续性标准后，我们会通过云控的方式将您的应用从relaunch名单中移除，待您的设备收到云控更新后，您的应用将不会再执行relaunch行为。

页面布局适配

Android 10 (API 级别 29) 或更高版本支持更多种宽高比。对于可折叠设备而言，设备类型可以是超长、超薄的屏幕（例如屏幕宽高比为 21:9 的折叠设备），也可以是 1:1 的屏幕，如要与尽可能多的设备兼容，需要尽量多针对以下屏幕宽高比测试自己的应用：

如果无法支持上述某些高宽比，可以使用 maxAspectRatio 以及 minAspectRatio 来指明自己应用可以处理的最高宽高比和最低宽高比，此属性需要在 AndroidManifest.xml 文件的 application 或者 actvivity 标签中添加。例如：

<application    
    android:maxAspectRatio="2.4">     
<activity          
        android:maxAspectRatio="2.4" />
</application>