小米开发平台Activity Embedding 适配指南
1、功能介绍
为了利用大屏幕的显示区域，Google在Jetpack WindowManager中添加了Activity Embedding，实现同一应用内不同activity分屏显示，开发者可以通过配置XML文件或者进行Jectpack WindowManager API调用确定如何显示activity（并排或堆叠）。
目前支持以下两种逻辑跳转，第一种是可以实现左容器界面固定:
第二种是支持多层次导航:
另外系统会自动维护对小屏幕的显示，当应用在小屏幕的设备上时，activity会相互堆叠，在大屏幕上，activity会并排显示，对于折叠屏，会随着设备折叠和展开而堆叠和并排显示activity。
2、快速上手
JetPack WindowManager库添加了ActivityEmbeddingComponent，可以根据分屏规则创建容器实现应用内分屏，配置分屏规则涉及到下面几个步骤：
2.1 添加依赖项
将WindowManager库依赖项添加到应用的build.gradle文件中
implementation("androidx.window:window:1.1.0-alpha02")2.2 配置分屏规则
2.2.1 XML静态配置
放在res资源文件的xml文件夹下
<!-- The split configuration for activities. -->
<resources
xmlns:window="http://schemas.android.com/apk/res-auto">
<!-- Automatically split the following activity pairs. -->
<SplitPairRule
window:clearTop="true"
window:splitMinWidth="600dp">
<SplitPairFilter
window:primaryActivityName=".SplitActivityList"
window:secondaryActivityName=".*"/>
</SplitPairRule>
<!-- Automatically launch a placeholder for the list activity. -->
<SplitPlaceholderRule
window:placeholderActivityName=".SplitActivityListPlaceholder"
window:splitRatio="0.3"
window:splitMinWidth="600dp">
<ActivityFilter
window:activityName=".SplitActivityList"/>
</SplitPlaceholderRule>
<!-- Automatically launch a full activity. -->
<ActivityRule window:alwaysExpand="true">
<ActivityFilter
window:activityName=".FullActivity"/>
</ActivityRule>
</resources>2.2.2 代码动态配置
运行时定义分屏的配置，开发者可以在startActivity或者onCreate时使用
splitController.registerRule(new SplitPairRule(newFilters));
splitController.unRegisterRule(new SplitPairRule(newFilters));
来动态添加/移除规则
protected void onCreate(@Nullable Bundle savedInstanceState) {
Set<SplitPairFilter> pairFilters = new HashSet<>();
SplitPairFilter filter = new SplitPairFilter(primaryActivityComponetName,
secondaryActivityComponetName,
null);
pairFilters.add(filter);
SplitPairRule pairRule = new SplitPairRule(pairFilters,
SplitRule.FINISH_ADJACENT,
SplitRule.FINISH_ALWAYS,
true,
600,
600,
0.3f,
LayoutDirection.LOCALE);
SplitController splitController = SplitController.getInstance();
splitController.registerRule(pairRule);
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
}2.3 将规则定义通知库
使用Jetpack Startup库在加载应用的其他组件和启动 activity 之前执行初始化。如需启用启动功能，请在应用的 build 文件中添加库依赖项：
implementation("androidx.startup:startup-runtime:1.1.0")并在manifest中添加：
<!-- AndroidManifest.xml -->
<provider android:name="androidx.startup.InitializationProvider"
android:authorities="${applicationId}.androidx-startup"
android:exported="false"
tools:node="merge">
<!-- This entry makes ExampleWindowInitializer discoverable. -->
<meta-data android:name="**androidx.window.sample.embedding.ExampleWindowInitializer**"
android:value="androidx.startup" />
</provider>2.4 添加初始化程序类实现
通过将包含定义 (main_split_config) 的 xml 资源文件的 ID 提供给 SplitController.initialize() 来设置规则：
class ExampleWindowInitializer extends Initializer<SplitController> {
@Override
SplitController create(Context context) {
SplitController.initialize(context, R.xml.main_split_config);
return SplitController.getInstance(context);
}
@Override
List<Class<? extends Initializer<?>>> dependencies() {
return emptyList();
}
}2.5 XML配置文件参数解析
| 参数 | 含义 |
| SplitPairRule | 分屏配对情景（两侧容器均有具体activity），对应SplitPairFilter |
| splitRatio | 分屏比默认为0.5f，即左右5：5分屏 ，对于IM类应用，可考虑设置分屏比为0.3f，即左右3：7分屏 |
| splitMinWidth | 默认配置600dp，宽度达到600dp才可以分屏，主窗口可分屏显示的最小窗口宽度 |
| splitMinSmallestWidth | 默认配置600dp，主窗口可分屏显示的最小sw值 |
| finishPrimaryWithSecondary | 默认为 false，true：若secondary container中所有activity都finish，则primary container中创建分屏的activity也会finish，不推荐应用主动配置此项。(androidx.window:window:1.1.0-alpha03中默认是SplitRule.FINISH_ADJACENT) |
| finishSecondaryWithPrimary | 默认为 ture， true：若primary container中所有activity都finish，则secondary container中所有activity也会finish，不推荐应用主动配置此项。(androidx.window:window:1.1.0-alpha03中默认是SplitRule.FINISH_ALWAYS) |
| clearTop | 默认为 false，true：启动activity窗口分屏，存在相同的primary container，若新建secondary container，则原secondary container中的activity会被finish掉，推荐应用配置，避免右分屏出现多实例 |
| SplitPairFilter | 分屏配对关系（必需配置） |
| primaryActivityName | 分屏的primay activity component name |
| secondaryActivityName | 分屏的secondary activity component name |
| secondaryActivityAction | 分屏的secondary activity 启动的action （配置此项需要在启动的时候添加action) |
| 参数 | 含义 |
| SplitPlaceholderRule | 用来描述分屏下的占位，对应ActivityFilter（必需配置） |
| placeholderActivityIntentName | 通过同时打开两个activity创建分屏，secondary占位activity component name |
| componentName | 组件名 |
| intentAction | intent |
| splitRatio | 分屏比默认为0.5f，即左右5：5分屏 |
| splitMinWidth | 默认配置600dp，宽度达到600dp才可以分屏主窗口可分屏显示的最小窗口宽度 |
| splitMinSmallestWidth | 默认配置600dp，主窗口可分屏显示的最小sw值 |
| ActivityFilter | 适配占位规则的activity（必需配置） |
| 参数 | 含义 |
| ActivityRule | 需要全屏显示的activity，对应ActivityFilter（必需配置） |
| alwaysExpand | 取值”true”或false true：启动的activity全屏显示 |
| componentName | 组件名 |
| intentAction | intent |
| ActivityFilter | 适配全屏规则的activity（必需配置） |
2.6 应用主动适配生效
2.6.1 MIUI meta-data标记
AndroidManifest.xml中声明下列meta-data字段。设置为true表示app已经主动适配，系统不会反向适配
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
<meta-data android:name="embedded" android:value="true"/>
</application>注意：
Android 13后该meta-data将不使用
2.6.2 Google property标记
Google官方添加property字段，用来标识APP是否允许系统反向适配Activity Embedding
true表示允许系统反向适配，false不允许系统反向适配
注意：自适配Activity Embedding和不允许系统反向适配Activity Embedding的APP需要设置为false
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application>
<property
android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE"
android:value="false" />
</applicatio3、适配指导
3.1 关于应用横竖屏
3.1.1 PAD 竖屏下进入ActivityEmbedding
平板设备处于竖屏状态时，我们推荐应用采用左下图的全屏显示样式，而不是进入ActivityEmbedding。竖屏下的左右分屏显示会导致信息量过多，难以聚焦。如果您的应用在竖屏下进入了ActivityEmbedding，原因是：应用设置的进入ActivityEmbedding的阈值splitMinWidth过小
- 获取屏幕大小
Ｒ版本之前：Display.getRealSize()、Display.getRealMetrics()。
Ｒ版本之后：WindowManager.getMaximumWindowMetrics() 。Jetpack WindowManager中支持使用WindowMetrics maximumWindowMetrics = WindowMetricsCalculator.
getOrCreate().computeMaximumWindowMetrics(activity);
- 获取当前窗口大小
Ｒ版本之前： Display.getSize() 。
Ｒ版本之后：WindowManager.getCurrentWindowMetrics() 。Jetpack WindowManager中支持使用WindowMetrics maximumWindowMetrics = WindowMetricsCalculator.
getOrCreate(). computeCurrentWindowMetrics(activity);
推荐解决方案：开发者根据不同屏幕大小的设备动态计算进入分屏的阈值。可使用如下计算方式：
// 获取屏幕大小
WindowMetrics currentWindowMetrics = WindowMetricsCalculator.getOrCreate().
computeCurrentWindowMetrics(activity);
// 获取当前窗口大小
WindowMetrics maximumWindowMetrics = WindowMetricsCalculator.getOrCreate().
computeMaximumWindowMetrics(activity);
// 通过configuration获取desity
float density = (float) activity.getResources().getConfiguration().densityDpi / 160f;
// 根据屏幕大小动态设置window:splitMinWidth="600dp"大小，控制竖屏下不进ActivtiyEmbedding
// 为了保证折叠屏外屏下不进入ActivityEmbedding，需要设置一下splitMinSmallestWidth的值，默认600dp
int splitMinWidth = (int) (Math.min(maximumWindowMetrics.getBounds().width(),
maximumWindowMetrics.getBounds().height()) / density + 1);3.1.2 PAD无法横屏
原因：ActivityEmbedding 只是改变activity的显示位置，不会强制更改方向，需要app支持横屏
推荐方案：第一个启动的activity方向设置为behind以及全屏启动的activity设置为behind
3.1.3 折叠屏控制在外屏竖屏显示
为了避免您适配ActivityEmbedding后在折叠屏外屏出现如下图所示的情况，需要控制应用在折叠屏外屏竖屏显示，监听 WindowInfoTracker 来手动设置方向，具体使用参考官方文档https://developer.android.com/guide/topics/large-screens/make-apps-fold-aware
3.2 支持resizeable
应用需要在 AndroidManifest.xml 文件的 application 或者 actvivity 标签中添加 resizeableActivity=true 的属性。
若配置android:resizeableActivity=“false”，会导致无法分屏显示
<application
android:resizeableActivity="true">
<activity
android:resizeableActivity="true" />
</application>3.3 关于Configuration
当应用在折叠屏内外屏或平板横竖屏交替使用时，activity的大小会发生变化，我们强烈推荐Activity在大小切换时不重启来保证良好的连续性体验，遵循google规范，在android:configChanges 属性增加 screenSize|screenLayout|orientation|smallestScreenSize，并在Activity的onConfigurationChanged回调中更新宽高刷新各个子布局。
3.4 视频全屏
分屏时请求横屏还是在分屏下显示，无法横屏全屏
建议配置activity 始终填满任务窗口：
<ActivityRule
window:alwaysExpand="true">
<ActivityFilter
window:activityName=".FullActivity"/>
</ActivityRule>3.5 clearTop标记
若配置为true
启动activity窗口分屏，存在相同的primary container，会创建新的secondary container，原来的secondary container中的activity会被finish掉，避免右分屏出现多实例。开发者可以根据需要对单独的SplitPairRule 进行配置clearTop=”true”。
用户折叠手机时，屏幕 B 在屏幕 A 之上，屏幕 A 又在菜单之上。当用户从屏幕 B 进行返回导航时，系统会显示屏幕 A 而不是Menu。
可以将分屏配置为通过 clearTop 清除之前的辅助容器，并正常启动新的 activity。
<SplitPairRule
window:clearTop="true">
<SplitPairFilter
window:primaryActivityName=".Menu"
window:secondaryActivityName=".ScreenA"/>
<SplitPairFilter
window:primaryActivityName=".Menu"
window:secondaryActivityName=".ScreenB"/>
</SplitPairRule>3.6 new Task与Launch Flag
当分屏任务窗口中的 activity 启动新任务中的 activity 时，新任务将与包含分屏的任务分开并显示在全窗口中。
在分屏任务窗口中，Launch flag同样起作用，可以复用activity。
3.7 多进程规则匹配
问题：同一Task任务下，子进程配置activity成全屏不生效
采用Jetpack Startup不指定android:process时默认在主进程初始化SplitController，在xml文件夹中的分屏规则不会在子进程生效
<!-- AndroidManifest.xml -->
<provider android:name="androidx.startup.InitializationProvider"
android:authorities="${applicationId}.androidx-startup"
android:exported="false"
tools:node="merge">
<!-- This entry makes ExampleWindowInitializer discoverable. -->
<meta-data android:name="**androidx.window.sample.embedding.ExampleWindowInitializer**"
android:value="androidx.startup" />
</provider>目前解决方案是需要重写Application在onCreate方法中对需要规则匹配的进程初始化SplitController并且加载静态规则。
public class MyApplication extends Application {
@Override
public void onCreate() {
SplitController.initialize(getApplicationContext(), R.xml.split_config);
super.onCreate();
}
}3.8 响应分屏状态变化
ActivityEmbedding下如何判断activity是否处于分屏以及window mode变化，如何实时响应分屏状态变化。
3.8.1 判断是否在左右分屏
左右分屏下，activity中的configuration的mode是multi-window(与系统分屏下的mode一样，在进行部分业务处理时需要注意）
全屏状态下，activity中的configuration的mode是fullscreen
判断当前activity是否在左右分屏状态，可以通过SplitController.getInstance().isActivityEmbedded(Activity activity)进行区分，返回true表示处于分屏。
3.8.2 如何响应分屏状态变化
为了知道 activity 何时在分屏中，可以向SplitController注册一个监听器来监听分屏状态的变化。然后，相应地调整界面：
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
splitController
.addSplitListener(this, mainThreadExecutor, SplitInfoChangeCallback());
}
class SplitInfoChangeCallback extends Consumer<List<SplitInfo>> {
public void accept(List<SplitInfo> splitInfoList) {
findViewById<View>(R.id.infoButton).visibility =
!splitInfoList.isEmpty()) ? View.GONE : View.VISIBLE;
}
}可以在任何生命周期状态下进行回调，包括当 activity 停止时。通常应在onStart()中注册监听器，在onStop()中取消注册监听器。
3.9 占位Activity Placeholder
如需创建带有占位符的分屏，请创建一个占位符并将其与主要 activity 相关联：
<SplitPlaceholderRule
window:placeholderIntentName=".Placeholder">
<ActivityFilter
window:activityName=".Main"/>
</SplitPlaceholderRule>注意：开发者不需要自己启动placeholder，会创建多个TaskFragment导致启动异常，在真正显示主页面时建议不启动placeholder，可以动态注册规则，比如在进入主界面前先跳转到登录界面，如果启动了placeholder有可能会导致异常。
