原创 Android 2025-06-20 17:31 北京
Jetpack WindowManager 1.4 稳定版引入了多项新功能，使多窗口模式体验变得更加强大和灵活。
Jetpack WindowManager 正在不断改进。WindowManager 为您提供构建自适应应用的工具，使您的应用可以在各种大屏设备上流畅运行。Jetpack WindowManager 1.4 稳定版引入了新功能，使多窗口模式体验变得更加强大和灵活。虽然 Jetpack Compose 仍然是为不同屏幕尺寸创建应用布局的最佳方案，但是 1.4 版本为 Activity 嵌入带来了一些重大改进，包括 Activity 堆栈固定、窗格扩展和对话框全屏调暗 (Dialog full-screen dim)。多 Activity 应用可轻松利用所有这些出色的特性。
WindowManager 1.4 新功能
WindowManager 1.4 引入了一系列增强功能，欢迎您继续阅读了解亮点功能。
WindowSizeClass
我们更新了 WindowSizeClass API 以支持自定义值，更改了 API 形态，使其易于扩展，以便支持自定义值和在未来添加新值。主要变更如下：
开放构造函数，允许传入 minWidthDp 和 minHeightDp 参数，以便您自行创建窗口大小类
添加了用于检查断点有效性的便捷方法
弃用了 WindowWidthSizeClass 和 WindowHeightSizeClass，推荐分别改为使用 WindowSizeClass#isWidthAtLeastBreakpoint() 和 WindowSizeClass#isHeightAtLeastBreakpoint()
🔗 WindowSizeClass
以下是一个迁移示例：
// old
val sizeClass = WindowSizeClass.compute(widthDp, heightDp)
when (sizeClass.widthSizeClass) {
COMPACT -> doCompact()
MEDIUM -> doMedium()
EXPANDED -> doExpanded()
else -> doDefault()
}
// new
val sizeClass = WindowSizeClass.BREAKPOINTS_V1
.computeWindowSizeClass(widthDp, heightDp)
when {
sizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_EXPANDED_LOWER_BOUND) -> {
doExpanded()
}
sizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND) -> {
doMedium()
}
else -> {
doCompact()
}
}
新 API 中的一些注意事项：
when 分支应遵循从大到小的顺序，以支持开发者提供的自定义值或未来的新值
默认分支应被视为最小的窗口大小类
Activity 嵌入
Activity 堆栈固定
Activity 堆栈固定提供了一种无论您的应用中出现何种情况都可使 Activity 堆栈始终显示在屏幕上的方法。您可以通过该功能将 Activity 堆栈固定到特定窗口。这样一来，即使用户在另一个窗口中导航到应用的其他部分，顶层 Activity 也会保持可见。如果您想要在用户浏览其他内容时，使某些内容保留在屏幕上 (例如实时聊天或视频播放器)，该功能会非常适用。
private fun pinActivityStackExample(taskId: Int) {
val splitAttributes: SplitAttributes = SplitAttributes.Builder()
.setSplitType(SplitAttributes.SplitType.ratio(0.66f))
.setLayoutDirection(SplitAttributes.LayoutDirection.LEFT_TO_RIGHT)
.build()
val pinSplitRule = SplitPinRule.Builder()
.setDefaultSplitAttributes(splitAttributes)
.build()
SplitController.getInstance(applicationContext).pinTopActivityStack(taskId, pinSplitRule)
}
窗格扩展
全新的窗格扩展功能 (也称为交互式分隔线) 允许您在分屏模式下在两个 Activity 之间创建视觉分隔。您可以将窗格分隔线设置为可拖动，以便用户实时调整窗格以及窗格中 Activity 的尺寸。用户可借此控制他们查看应用内容的方式。
val splitAttributesBuilder: SplitAttributes.Builder = SplitAttributes.Builder()
.setSplitType(SplitAttributes.SplitType.ratio(0.33f))
.setLayoutDirection(SplitAttributes.LayoutDirection.LEFT_TO_RIGHT)
if (WindowSdkExtensions.getInstance().extensionVersion >= 6) {
splitAttributesBuilder.setDividerAttributes(
DividerAttributes.DraggableDividerAttributes.Builder()
.setColor(getColor(context, R.color.divider_color))
.setWidthDp(4)
.setDragRange(
DividerAttributes.DragRange.DRAG_RANGE_SYSTEM_DEFAULT)
.build()
)
}
val splitAttributes: SplitAttributes = splitAttributesBuilder.build()
🔗 窗格扩展
https://m3.material.io/foundations/layout/applying-layout/pane-layouts#d3ef6c37-d8a5-4029-99d1-033ec6db39a6
对话框全屏调暗
WindowManager 1.4 可助您更好地控制对话框调暗背景的方式。通过对话框全屏调暗 (Dialog full-screen dim) 功能，您可以选择仅调暗显示对话框的容器，或调暗整个任务窗口，以获得统一的界面体验。默认情况下，当对话框打开时，整个应用窗口都会变暗 (请参阅 EmbeddingConfiguration.DimAreaBehavior.ON_TASK)。如果只想调暗打开对话框的 Activity 的容器，请使用 EmbeddingConfiguration.DimAreaBehavior.ON_ACTIVITY_STACK。您可以借此更灵活地设计对话框，同时提供更流畅、更连贯的用户体验。Temu 是首批集成此功能的开发者之一，他们表示对话框全屏调暗功能使屏幕上的无效触碰次数减少了约 5%。
🔗 EmbeddingConfiguration.DimAreaBehavior.ON_TASK
🔗 EmbeddingConfiguration.DimAreaBehavior.ON_ACTIVITY_STACK
https://developer.android.com/reference/androidx/window/embedding/EmbeddingConfiguration.DimAreaBehavior#ON_ACTIVITY_STACK%28%29
增强的折叠状态支持
WindowManager 1.4 可提供有关设备物理性能的更多信息，助您轻松构建能够在可折叠设备上流畅运行的应用。全新的 WindowInfoTracker#supportedPostures API 可让您知道设备是否支持桌面模式，以便您可以相应地优化应用的布局和功能。
val currentSdkVersion = WindowSdkExtensions.getInstance().extensionVersion
val message =
if (currentSdkVersion >= 6) {
val supportedPostures = WindowInfoTracker.getOrCreate(LocalContext.current).supportedPostures
buildString {
append(supportedPostures.isNotEmpty())
if (supportedPostures.isNotEmpty()) {
append(" ")
append(
supportedPostures.joinToString(
separator = ",", prefix = "(", postfix = ")"))
}
}
} else {
"N/A (WindowSDK version 6 is needed, current version is $currentSdkVersion)"
}
🔗 WindowInfoTracker#supportedPostures
https://developer.android.com/reference/kotlin/androidx/window/layout/WindowInfoTracker#supportedPostures%28%29
其他 API 变更
WindowManager 1.4 包含多项 API 变更和新增功能，用于支持新特性。显著变更包括：
以下 API 现已提供稳定版，不再是实验性 API：
ActivityEmbeddingController#invalidateVisibleActivityStacks
ActivityEmbeddingController#getActivityStack
SplitController#updateSplitAttributes
新增了以下 API，用于设置 Activity 嵌入动画背景：
SplitAttributes.Builder#setAnimationParams
以下 API 可用于获取更新后的 WindowMetrics 信息：
ActivityEmbeddingController#embeddedActivityWindowInfo
以下 API 可用于结束 Activity 堆栈中的所有 Activity：
ActivityEmbeddingController#finishActivityStack
使用指南
要开始在您的 Android 项目中使用 Jetpack WindowManager 1.4，请将 build.gradle.kts 中的应用依赖项更新为最新稳定版：
dependencies {
implementation("androidx.window:window:1.4.0-rc01")
...
// or, if you're using the WindowManager testing library:
testImplementation("androidx.window:window-testing:1.4.0-rc01")
}
乐享编码！欢迎您持续关注 "Android 开发者" 微信公众号，及时了解更多开发技术和产品更新等资讯动态！
