Jetpack WindowManager 1.4 稳定版发布

Jetpack WindowManager 持续优化升级

Jetpack WindowManager 为开发者提供构建自适应应用的工具，助力应用在不同大屏设备间无缝运行。现已推出 1.4 稳定版，通过多项新特性显著增强多窗口体验。虽然 Jetpack Compose 仍是构建多尺寸布局的最佳方案，但 1.4 版本针对 Activity Embedding 进行了重大改进，包括 Activity Stack Pinning（活动堆栈固定）、Pane Expansion（窗格扩展）和 Dialog Full-Screen Dim（对话框全屏遮罩）等功能。多 Activity 应用现可轻松集成这些特性。

WindowManager 1.4 更新亮点

WindowSizeClass 增强

我们重构了 WindowSizeClass API 以支持自定义值，提升 API 的可扩展性。主要变化包括：

开放构造函数参数：新增 minWidthDp 和 minHeightDp 参数，支持创建自定义窗口尺寸分类
新增便捷方法：简化断点有效性校验流程
弃用旧版类：使用 WindowSizeClass#isWidthAtLeastBreakpoint() 和 WindowSizeClass#isHeightAtLeastBreakpoint() 替代 WindowWidthSizeClass 和 WindowHeightSizeClass

迁移示例如下：

// 旧版
val sizeClass = WindowSizeClass.compute(widthDp, heightDp)
when (sizeClass.widthSizeClass) {
  COMPACT -> doCompact()
  MEDIUM -> doMedium()
  EXPANDED -> doExpanded()
  else -> doDefault()
}

// 新版
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 Embedding 强化

Activity Stack Pinning

该特性可将 Activity 堆栈固定显示在屏幕特定区域，即使其他窗口进行导航操作，顶部 Activity 仍保持可见（适用于视频播放、实时聊天等场景）：

private fun pinActivityStackExample(taskId: Int) {
  val 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)
}

Pane Expansion

新增可交互分隔条功能，支持用户拖拽调整分屏尺寸：

val splitAttributesBuilder = 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()
  )
}

Dialog Full-Screen Dim

新增遮罩范围控制选项：

默认行为 (EmbeddingConfiguration.DimAreaBehavior.ON_TASK)：全窗口遮罩
局部遮罩 (EmbeddingConfiguration.DimAreaBehavior.ON_ACTIVITY_STACK)：仅遮罩 Activity 所在容器

案例：Temu 集成该功能后，屏幕误触率降低约 5%

Customised shopping cart reminder with dialog full-screen dim in Temu

增强对折叠形态的支持

通过 WindowInfoTracker#supportedPostures API 检测设备折叠形态支持（如 Tabletop Mode）：

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(" ${supportedPostures.joinToString(",", "(", ")")}")
    }
  }
} else {
  "N/A (Requires WindowSDK 6, current version is $currentSdkVersion)"
}

其他 API 变更

稳定 API

ActivityEmbeddingController#invalidateVisibleActivityStacks
ActivityEmbeddingController#getActivityStack
SplitController#updateSplitAttributes

新增 API

设置动画背景：SplitAttributes.Builder#setAnimationParams
获取窗口度量信息：ActivityEmbeddingController#embeddedActivityWindowInfo
结束 Activity 堆栈：ActivityEmbeddingController#finishActivityStack

集成指南

在 build.gradle.kts 中添加依赖：

dependencies {
    implementation("androidx.window:window:1.4.0") 
    // 测试库
    testImplementation("androidx.window:window-testing:1.4.0")
}

英文原文：https://android-developers.googleblog.com/2025/03/jetpack-windowmanager-14-is-stable.html
原文作者：Xiaodao Wu - Developer Relations Engineer

版权声明
禁止一切形式的转载-禁止商用-禁止衍生申请授权

Jetpack WindowManager 1.4 稳定版发布