小米大屏设备适配说明3

3.5 H5页面适配

我们推荐项目使用响应式设计，实现同一页面自动适配多种屏幕尺寸的效果。

3.5.1 元标签设置

通常情况下，开发者应使用元标签将视口大小调整为屏幕宽度，以确保元素尺寸按照预期显示。

<meta name="viewport" content="width=device-width,initial-scale=1">

开发者可以提供额外的参数来限制用户的缩放行为，一般来说这样做可以优化普通用户体验，减少误操作，但会影响视力障碍用户进行缩放操作，造成访问性问题。

<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no">

3.5.2 使用相对 CSS 长度单位

我们推荐开发者在响应式开发中尽量使用相对长度单位，包括：em、rem、%、vw、vh。以下是这些单位的一般使用场景。

上述的只是一般情况，实际开发中使用哪个单位还需视设计要求而定，合理使用长度单位能起到事半功倍的效果。

3.5.3 布局方式

在响应式开发中，开发者应优先使用以下方式进行布局，构建适应性更强的页面。

A.Flexbox（弹性布局）

使用display: flex 可令容器元素启用弹性布局。即使在不确定容器内元素尺寸的情况下，开发者也可以灵活控制元素的大小比例和对齐方式。

参考资料

B.Grid（栅格布局）

Flexbox 可以很好地解决同一行/列内元素的布局问题，Grid 则更适合用于拥有多行/列的二维布局。使用display: grid 可令容器元素启用栅格布局。开发者可灵活控制行列间距、大小比例、对齐方式。

参考资料

3.5.4 CSS 媒体查询

使用 CSS 媒体查询技术，可以使同一元素的样式在不同设备下有不同的表现。通常，我们使用设备屏幕宽度作为判断设备类型的依据，以下是我们推荐的断点划分规则。

一般情况下，建议开发者使用媒体查询统一控制根字体大小，简化适配流程。

html {  
  font-size: 16px;
}
@media screen and (min-width: 480px) {
  html {
    font-size: 17px;
  }
}
@media screen and (min-width: 680px) {
  html {
    font-size: 18px;
  }
}

3.5.5 Javascript 媒体查询

在一些特殊情况下，页面需要根据断点进行更加复杂的调整。如页面文案，交互逻辑等需要随断点而变化。此时需要使用 Javascript 进行更加细微的调整，我们推荐开发者使用matchMedia 方法进行断点识别，断点划分方案建议与 CSS 方案保持一致。

参考资料

3.5.6 其他建议

1）使用响应式图片，用于图片进行尺寸匹配的场景。

img {
  /* 按比例拉伸或缩放至父元素宽度 */
  width: 100%  }

img {
 /* 按比例缩放至父元素宽度，不拉伸 */
  max-width: 100%  
}

img {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  /* 按比例拉伸或缩放至父元素宽高 */
  object-fit: cover;
  object-position: center;
}

2）为块级元素添加 max-width 而非 width，避免在更小尺寸的显示设备上宽度溢出。

4、平行窗口适配指南

推荐采用Android 12L方案进行适配，您可自主定义activity在左右分屏间的跳转方式。

详细参考Android适配文档、Sample，Activity Embedding 适配指南

平行窗口适配情况标记

应用主动适配12L平行窗口，需要在AndroidMainfest.xml文件设置标记。

<!-- support 12L Activity Embedding for large screen -->
        <meta-data
            android:name="embedded"
            android:value="true" />

5、进阶开发适配指南(小窗、迷你窗及分屏)

5.1 小窗迷你窗功能介绍

5.1.1 小窗

在多任务处理场景下，小窗意在解决临时使用某个应用的场景，例如：在使用游戏应用时，不便离开，但想发消息给朋友，此时就可以借助小窗打开第二应用

5.1.2 迷你窗

迷你小窗意在解决应用临时挂机的场景，例如：等待网约车、等待游戏更新、观看直播等

5.2 小窗迷你窗适配指南

小窗适配技术文档

MIUI的小窗是基于Android的多窗口Freeform方案实现的。

小窗目前主要问题是应用兼容性导致的一系列问题，内容显示不全、Touch事件不响应等等，其实根本原因是应用没有很好的支持、适配多窗口、多分辨率，如下是小窗适配的一些参考性适配指南。

多窗口适配支持文档

支持不同屏幕分辨率的开发技巧文档

5.2.1 常用适配方法

（1） 如何支持小窗

支持小窗的方式非常简单，只需要声明一个属性，直接在AndroidManifest.xml中 配置属性android:resizeableActivity=”true” ，不支持小窗直接配置为false，系统默认是支持小窗的。

（2）判断自己是否在小窗  

Activity.onMultiWindowModeChanged(boolean isInMultiWindowMode, Configuration  newConfig)  
Activity.isInMultiWindowMode()   判断是否处于多窗口                                                    
Activity.getWindowingMode()  当返回5时表示小窗，需要反射调用
String config = context.getResources().getConfiguration().toString();
boolean isInFreeformWindow = config.contains("freeform");

（3）获取小窗的位置/大小等信息

context.getResources().getConfiguration().windowConfiguration.getBounds()，其中Configuration对象里也有小窗的模式以及bounds,所以我们也需要重写ConfigurationChanged方法，并对界面布局做相应调整，如切换布局、调整控件位置和间距等。

（4）Activity大小切换时不重启适配

强烈建议应用在Activity窗口大小切换时不重启适配，遵循google规范，在android:configChanges 属性增加 screenSize|screenLayout|orientation|smallestScreenSize，并在Activity的onConfigurationChanged回调中更新宽高刷新各个子布局。

（5）特别需要注意的适配点,焦点窗口适配

迷你小窗和小窗都有可能成为不是焦点窗口(Focus Window)，其中迷你小窗一定是没有焦点的，小窗和小窗下面的全屏应用是可以随意进行焦点切换的，touch在哪个窗口，哪个窗口就是焦点窗口，所以就要保证应用在没有焦点的前提下也是可以正常运行的，特别是视频类app。关键方法：Activity.onWindowFocusChanged(boolean hasFocus)

（6）获取屏幕宽高有些APP会跟随屏幕大小动态计算View的大小,但是有些接口在多窗口形式下面并不试用,要注意以下几点:

• 在获取Display 对象 或者获取 Resources对象时使用Activity的Context 不要使用Application的Context；
• 获取Resources对象时不要用context.getResources().getSystem()用context.getResources()就行；
• Display下有getMetrics getRealMetrics getSize getRealSize四个方法, getRealMetrics和 getRealSize 永远会返回屏幕的宽高,无论应用是否在多屏下, 而getMetrics和getSize会可以获取Activity的大小。

（7）获取View的位置

获取View的位置有两个方法:

• View.getLocationInWindow(int[] outLocation) 返回距离View所在的Window左上角的距离；
• View.getLocationOnScreen 返回距离屏幕左上角的距离(由于在小窗模式下应用的位置可以移动, 所以该返回值有时并非是你想要的,所以要慎用)。

5.2.2 其他说明

全局自由窗口功能在MIUI12安卓Q版本以上支持。

如果应用想要启用小窗或者分屏模式下的拖拽功能，请参考如下google资料进行适配：

Android Developer上的拖放文档

AOSP里的DragAndDrop样例应用

github Demo下载连接

5.3 分屏功能介绍

分屏场景意在解决长时间并行使用两个应用时的场景，例如：一边听网课，一边记笔记等；一边看视频，一边逛知乎、微博等

5.4 分屏适配技术文档

小米大屏设备适配说明2

2.3 不同类型应用适配建议

针对不同行业，不同类型应用，我们推荐以下五种布局方案：多列布局，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>

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

小米开发平台屏幕指纹设备适配说明

1. 什么是屏下指纹

小米 8 透明探索版中，我们引入屏下指纹这项新技术，即指纹传感器嵌入屏幕下。

由于是屏下指纹，所以需要出现指纹图标，提示用户指纹传感器的位置，但这样会和部分需要使用指纹验证的业务产生冲突。

2. 屏下指纹相关接口

由于各个开发者的指纹验证逻辑和 UI 样式非常不一样，所以系统不打算统一大家的样式，而是会提供相关接口，由各业务组做针对性地适配。

2.1. 是否为屏下指纹设备

// true means FOD project
PRODUCT_PROPERTY_OVERRIDES += ro.hardware.fp.fod=true

2.2. 指纹传感器的位置、大小（每次指纹验证都需要重新获取）

以下是 Android O 的接口：

//location of FOD sensor's top left corner in pixel, the top left corner of screen is (0,0)
//persist.sys.fp.fod.location.X_Y 表示sensor区域左上角的坐标，以pixel为单位，以物理屏幕左上角为（0,0）计算。
persist.sys.fp.fod.location.X_Y = 453,1640

//sensor的大小（单位也是pixel）
persist.sys.fp.fod.size.width_height = 173,173

以下是 Android P 的接口（应谷歌要求，需要加入「vendor」字样）

//location of FOD sensor's top left corner in pixel, the top left corner of screen is (0,0)
// persist.vendor.sys.fp.fod.location.X_Y 表示sensor区域左上角的坐标，以pixel为单位，以物理屏幕左上角为（0,0）计算。
persist.vendor.sys.fp.fod.location.X_Y = 453,1640

//sensor的大小（单位也是pixel）
persist.vendor.sys.fp.fod.size.width_height = 173,173

因为同一款设备，市场上可能会同时存在 Android O 和 Android P 两个版本，所以开发者需要根据 Android 版本调用不同的接口，以获取正确的位置信息。

2.3. 控制指纹图标显示、消失

调用标准的指纹监听接口即可显示指纹图标。

2.4. 指定指纹图标的颜色（黑色或白色）

由于各个业务组的界面不尽相同，我们会提供一个接口，让业务方指定要用「黑色」还是「白色」的指纹图标。

复用原有 flag 中的「0」「1」标志（原flag标志没有使用），0表示黑色，1表示白色。

mFm.authenticate(null, mCancellationSignal, 0, callback, null); // 黑色指纹图标（默认）
mFm.authenticate(null, mCancellationSignal, 1, callback, null); // 白色指纹图标

3. 屏下指纹适配建议

3.1. UI 避开指纹传感器的位置

业务方可以通过上述接口获取指纹图标的位置和大小，建议控件、键盘等元素都避开那个区域。

3.2. 不建议同时支持密码验证和指纹验证

由于指纹图标会挡住键盘，所以不建议开发者同时支持指纹和密码验证，而是做成互斥的模式，类似微信支付。

3.3. 考虑是否需要调整正确、错误的反馈

如果第三方调用，系统不处理指纹验证正确或错误的反馈，交由开发者自行处理。开发者可以根据自身业务逻辑，考虑是否需要针对屏下指纹调整相关反馈。

4. FAQ

4.1. 有几款机型支持屏下指纹

小米机型中，目前支持屏下指纹的设备为「小米 8 透明探索版」和「小米8 屏幕指纹版」。

4.2. 如何测试

拿到设备后，建议同时测试以下两个版本的效果：

• MIUI 9 稳定版，即出厂自带的版本，截至2018年底仍会是该机型用户的主要版本。
• MIUI 10 开发版或稳定版，后续 MIUI 10 将成为 MIUI 系统的主流，又因为 System UI 的代码架构在MIUI 10有较多调整，所以建议同时覆盖测试。

顺便附上ROM下载链接如下：

• 国内版 ROM：https://www.miui.com/download.html
• 国际版 ROM：http://en.miui.com/download.html