WindowManager

借助 Jetpack WindowManager 库,应用开发者可为新的设备外形规格和多窗口环境提供支持。该库为 API 版本 14 及更高版本提供通用的 API 接口。初始版本以可折叠设备为目标,不过未来版本将支持更多屏幕类型和窗口功能。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2024 年 3 月 6 日 1.2.0 - - 1.3.0-alpha03

声明依赖项

如需添加 WindowManager 的依赖项,您必须将 Google Maven 代码库添加到项目中。有关详情,请阅读 Google 的 Maven 制品库

在应用或模块的 build.gradle 文件中添加所需工件的依赖项:

Groovy

dependencies {
    implementation "androidx.window:window:1.2.0"

    // For Java-friendly APIs to register and unregister callbacks
    implementation "androidx.window:window-java:1.2.0"

    // For RxJava2 integration
    implementation "androidx.window:window-rxjava2:1.2.0"

    // For RxJava3 integration
    implementation "androidx.window:window-rxjava3:1.2.0"

    // For testing
    implementation "androidx.window:window-testing:1.2.0"
}

Kotlin

dependencies {
    implementation("androidx.window:window:1.2.0")

    // For Java-friendly APIs to register and unregister callbacks
    implementation("androidx.window:window-java:1.2.0")

    // For RxJava2 integration
    implementation("androidx.window:window-rxjava2:1.2.0")

    // For RxJava3 integration
    implementation("androidx.window:window-rxjava3:1.2.0")

    // For testing
    implementation("androidx.window:window-testing:1.2.0")
}

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题,或对此库有任何改进建议,请告诉我们。创建新问题前,请先查看此库中的现有问题。您可以点击星标按钮,为现有问题投票。

创建新问题

如需了解详情,请参阅问题跟踪器文档

版本 1.3

版本 1.3.0-alpha03

2024 年 3 月 6 日

发布了 androidx.window:window-*:1.3.0-alpha03。版本 1.3.0-alpha03 中包含这些提交内容

API 变更

  • WindowSizeClassUtil 拆分为更有针对性的方法。(Ie9292
  • 恢复了 WindowSizeClass#computeI21355b/324293374

bug 修复

  • 修复了所提供的上下文未正确解封装的崩溃问题。(94d10ceb/318787482

版本 1.3.0-alpha02

2024 年 2 月 7 日

发布了 androidx.window:window-*:1.3.0-alpha02版本 1.3.0-alpha02 中包含这些提交内容

新功能

  • 对 Window Size Class API 的 API Surface 进行了更新,以便为希望使用自己的大小类的开发者提高灵活性。

API 变更

  • 为宽度选择器添加高度约束条件。(I23393
  • 添加了用于从集中选择 WindowSizeClass 的实用函数。添加了实验性评分函数,以便开发者可以编写自己的选择器。添加一个选择器扩展函数,以选择给定边界内最宽的 WindowSizeClass。(I0c944
  • 打开 WindowSizeClass 构造函数,以便添加自定义断点。(Ic1ff3)
  • 添加了根据宽度、高度和密度创建大小类别的便捷函数。(If67f4)

bug 修复

  • 修复了浮点值被截断为 0 时的异常。(272ffac)

版本 1.3.0-alpha01

2023 年 11 月 15 日

发布了 androidx.window:window-*:1.3.0-alpha01版本 1.3.0-alpha01 中包含这些提交内容

新功能

  • 公开了用于访问后屏幕的实验性窗口 API。
  • 用于创建 FoldingFeature 的测试 API 现已稳定。
  • 用于设置虚假 ActivityEmbedding 值的测试 API 现已稳定。
  • WindowLayoutInfoPublisherRule 在从 UiContext 获取值时现在会报告替换项。
  • WindowInfoTracker 会将折叠功能数据报告给 UiContext 参数。
  • 在设备上公开扩展程序版本。
  • WindowProperties 常量,用于按应用替换用户:
    • PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE - 告知系统,应用已选择不进行面向用户的宽高比兼容性替换。
    • PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE - 告知系统,应用已选择停用用户宽高比兼容性替换设置的全屏选项

版本 1.2

版本 1.2.0

2023 年 11 月 15 日

发布了 androidx.window:window-*:1.2.0版本 1.2.0 中包含这些提交内容

自 1.1.0 以来的重要变更

  • 公开了用于访问后屏幕的实验性窗口 API。
  • 用于创建 FoldingFeature 的测试 API 现已稳定。
  • 用于设置虚假 ActivityEmbedding 值的测试 API 现已稳定。
  • WindowLayoutInfoPublisherRule 在从 UiContext 获取值时现在会报告替换项。
  • WindowInfoTracker 会将折叠功能数据报告给 UiContext 参数。
  • 在设备上公开扩展程序版本。

版本 1.2.0-rc01

2023 年 11 月 1 日

发布了 androidx.window:window-*:1.2.0-rc01版本 1.2.0-rc01 中包含这些提交内容

新功能

  • 公开了用于访问后屏幕的实验性窗口 API。
  • 用于创建 FoldingFeature 的测试 API 现已稳定。
  • 用于设置虚假 ActivityEmbedding 值的测试 API 现已稳定。
  • WindowLayoutInfoPublisherRule 在从 UiContext 获取值时现在会报告替换项。
  • WindowInfoTracker 会将折叠功能数据报告给 UiContext 参数。
  • 在设备上公开扩展程序版本。

版本 1.2.0-beta04

2023 年 10 月 18 日

发布了 androidx.window:window-*:1.2.0-beta04版本 1.2.0-beta04 中包含这些提交内容。

API 变更

版本 1.2.0-beta03

2023 年 9 月 20 日

发布了 androidx.window:window-*:1.2.0-beta03版本 1.2.0-beta03 中包含这些提交内容

新功能

  • 针对需要特定版本的扩展程序才能正常运行的 API 添加了 RequiresApi 检查。
  • 添加了一个 API,用于在设备上公开扩展版本。

API 变更

  • 为公共 API 上所需的窗口 SDK 扩展版本添加注解。
    • 移除了 activity 嵌入组件中的 isXXXSupported。(Ie3dae)
  • 引入了 WindowSdkExtensions,用于报告设备上的扩展版本。
    • 引入了 RequiresWindowSdkExtension 以注解所需的最低扩展程序版本。(I05fd4)
  • 使 WindowAreaInfo#getCapability 不可为 null。(I17048

版本 1.2.0-beta01

2023 年 7 月 26 日

发布了 androidx.window:window-*:1.2.0-beta01版本 1.2.0-beta01 中包含这些提交内容

新功能

  • 公开了用于访问后屏幕的实验性窗口 API。
  • 用于创建 FoldingFeature 的测试 API 现已稳定。
  • 用于设置虚假 ActivityEmbedding 值的测试 API 现已稳定。
  • WindowLayoutInfoPublisherRule 在从 UiContext 获取值时现在会报告替换项。
  • WindowInfoTracker 会将折叠功能数据报告给 UiContext 参数。

API 变更

  • WindowArea API 标记为实验性 API,以允许 API 变更继续在稳定版本 1.3 中发挥作用。(I857f5)
  • 更新了 API 文件,以便为兼容性抑制添加注解。(I8e87ab/287516207

版本 1.2.0-alpha03

2023 年 6 月 21 日

发布了 androidx.window:window-*:1.2.0-alpha03版本 1.2.0-alpha03 中包含这些提交内容

新功能

  • 从 API Surface 中移除了已废弃的 API。
  • 添加了用以支持并发显示的 API。
  • 添加了用以停用强制性大小调整替换项的属性。
  • 添加了用以停用最小宽高比替换项的属性。
  • 稳定了 ActivityEmbeddingRule,以支持围绕 activity 嵌入的单元测试。

API 变更

  • 移除了已废弃的 API。(I18d39)
  • 添加了对并发显示的支持。(Ifcbb0)

bug 修复

  • 添加了用于停用强制性大小调整替换项的 compat 属性。(Ie7ab1)
  • 从扩展程序接口移除了 SESSION_STATE_CONTENT_INVISIBLE。(I6ed19)
  • 稳定了 ActivityEmbeddingRule,以支持围绕 activity 嵌入的单元测试。(I8d6b6)
  • 添加了用于停用最小宽高比替换项的 compat 属性。(I66390)
  • 移除了已废弃的 WindowArea API。(Ieb67c)
  • 将屏幕方向请求循环属性重命名为了 PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED。(Ie2fbd)
  • 更新了窗口区域会话常量名称。(I83675)
  • 添加了用于停用的 compat 属性,该属性会在检测到屏幕方向请求循环时将其忽略。(I0a7a2)
  • 添加了 WindowAreaComponent#STATUS_ACTIVE,用于表示相应功能已处于活动状态。(I62bc3)
  • 添加了 RearDisplayPresentationMode API。(I0401c)
  • 移除了背景颜色 API,以保持稳定。(I34c3e)
  • 隐藏了窗口区域 API。(I39de0)
  • 添加了用于替换 SplitController 中的 SplitInfo 的方法。添加了用于为 SplitInfoActivityStack 创建替身的测试方法。(Icd69f)
  • ActivityRule.Builder 的标记设置成了可选标记。(Ib0b44)
  • 移除了 RatioSplitTypeExpandContainersSplitHingeSplitType。它们现在都整合成了 SplitType
    • #splitEqually()#expandContainers()#splitByHinge 替换成了常量 SplitType SPLIT_TYPE_EQUALSPLIT_TYPE_EXPANDSPLIT_TYPE_HINGE
    • 移除了设置后备合页分屏类型的功能。如果由于当前设备或窗口状态而无法应用合页分屏类型,则回退为均分父级任务容器。使用 SplitController#setSplitAttributesCalculator 可以自定义后备分屏类型。(Ifcc59)
  • 废弃了 add/removeSplitCallback
    • add/removeSplitCallback 移到了 SplitControllerCallbackAdapter
    • 添加了 Flow 支持,以获取 SplitInfo 列表。(I7f1b6)
  • ActivityEmbeddingController 添加了测试规则。(I42e9b)
  • ActivityOptionsCompat 重命名为了 ActivityEmbeddingOptions。(I89301)
  • 添加了 splitSupportStatus,以指明 activity 嵌入功能是否可用。(I10024)
  • 引入了 SplitAttributes.BackgroundColor,以更好地表示 DEFAULT 值。明确指出不支持非不透明动画背景颜色,因此任何非不透明颜色都将被视为默认颜色,这意味着系统将使用当前主题窗口背景颜色。(Ic6b95)
  • alwaysAllow()alwaysDisallow() 替换为了 ALWAYS_ALLOWALWAYS_DISALLOW。(I3057b)
  • SplitRuleSplitAttributesSplitAttributesCalculator 添加了 API。(I92d23)
  • 添加了 TestActivityStack,以创建用于测试的 ActivityStack
    • 添加了 TestSplitInfo,以创建用于测试的 SplitInfo。(I8e779)
  • 添加了创建虚假 SplitAttributesCalculatorParams 的方法,这样一来,开发者就可以验证其自定义的 SplitAttributesCalculator。(Id4a6e)
  • 添加了 WindowMetricsCalculator#computeCurrentWindowMetrics(@UiContext context: Context)WindowMetricsCalculator#computeMaximumWindowMetrics(@UiContext context: Context)。(I66c7f)

版本 1.2.0-alpha02

2023 年 6 月 7 日

发布了 androidx.window:window-*:1.2.0-alpha02版本 1.2.0-alpha02 中包含这些提交内容

新功能

  • 更新测试 API,以为未指定的折叠功能提供常量。
  • 如果使用 WindowLayoutInfoPublishRule 进行替换,将替换掉 windowLayoutInfo 的所有值,包括基于上下文的 API。

API 变更

  • 为未指定的中央折叠功能添加了常量。(I7530c)

bug 修复

  • 更新了 WindowLayoutInfoPublishRule,以支持在基于 ContextWindowLayoutInfo 上进行替换操作。(I2037a)

版本 1.2.0-alpha01

2023 年 5 月 24 日

发布了 androidx.window:window-*:1.2.0-alpha01版本 1.2.0-alpha01 中包含这些提交内容

新功能

稳定了围绕 activity 嵌入和 WindowLayoutInfoTracker 的测试 API。ActivityEmbeddingRule 已提升到稳定版。WindowMetricsCalculatorRule 也已提升到稳定版。用于创建测试用 FoldingFeature 的实用函数也已提升到稳定版。

API 变更

  • 稳定了 ActivityEmbeddingRule,以支持围绕 activity 嵌入的单元测试。(I8d6b6)
  • WindowMetrisCalculatorTestRule 现已稳定,从而允许 JVM 测试使用桩指标。我们建议使用模拟器,以确保结果的准确性。
  • 稳定了 WindowLayoutInfo 的测试 API,以支持 JVM 测试。(Ie036e)
  • 添加了用于测试折叠功能值的 IntRange。(I69f7d)

版本 1.1

版本 1.1.0

2023 年 6 月 7 日

发布了 androidx.window:window-*:1.1.0版本 1.1.0 中包含这些提交内容

自 1.0.0 以来的重要变更

activity 嵌入

  • 添加了 PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED,并将其作为应用清单中 <application> 标记的布尔属性。
  • 废弃了 isSplitSupported 并代之以 splitSupportStatus,以详细说明分屏功能不可用的原因。
  • 添加了 SplitController.SplitSupportStatus 嵌套类,以为 splitSupportStatus 属性提供状态常量。
  • SplitController 重构为了几个模块:
    • ActivityEmbeddingController 模块,适用于 ActivityActivityStack 相关 API。
    • isActivityEmbeddedSplitController 移动到了 ActivityEmbeddingController
    • RuleController 模块,用于完成 EmbeddingRule 相关操作:
    • 移除了 SplitController API:
    • clearRegisteredRules()
    • getSplitRules()
    • initialize()
    • registerRule()
    • unregisterRule()
    • 添加了 RuleController API:
    • addRule() - 添加规则或更新具有相同标记的规则。
    • removeRule() - 从已注册规则集合中移除规则。
    • setRules() - 建立规则集合。
    • clearRules() - 移除所有已注册规则。
    • parseRules() - 根据 XML 规则定义解析规则。
  • 所有模块都需要通过 #getInstance() 方法初始化上下文,包括:
    • ActivityEmbeddingController#getInstance(Context)
    • SplitController#getInstance(Context)
    • RuleController#getInstance(Context)
  • 添加了 EmbeddingAspectRatio 类,以定义与显示宽高比相关的枚举类行为常量。
  • 添加了 SplitAttributes 类,以定义分屏布局。
  • SplitController 中添加了 SplitAttributes 计算器函数,以自定义分屏布局:
    • setSplitAttributesCalculator(Function)
    • clearSplitAttributesCalculator()
    • isSplitAttributesCalculatorSupported(),用于检查设备是否支持 SplitAttributesCalculator API
  • 添加了 EmbeddingRule#tag 字段。
  • SplitRule 中的 API 更新:
    • 添加了 defaultSplitAttributes,用于定义分屏的默认分屏布局;替换了 splitRatiolayoutDirection
    • defaultSplitAttributes 中添加了 XML 属性 splitRatiosplitLayoutDirection 的转换结果。
    • 更改了最小尺寸的定义,以使用密度无关像素 (dp) 而不是像素。
    • 添加了 minHeightDp,并将默认值设为 600dp。
    • minWidth 变更为了 minWidthDp,并将默认值设为 600dp。
    • minSmallestWidth 变更为了 minSmallestWidthDp,并将默认值设为 600dp。
    • 添加了 maxAspectRatioInHorizontal,并将默认值设为 ALWAYS_ALLOW
    • 添加了 maxAspectRatioInPortrait,并将默认值设为 1.4。
    • 定义了 FinishBehavior 嵌套类,用以替换完成行为常量。
    • 将属性更改应用到了 SplitPairRuleSplitPlaceholderRule 的 Builder 嵌套类。
  • SplitInfo#getSplitRatio() 替换成了 SplitInfo#getSplitAttributes(),以提供更多的分屏相关信息。

WindowLayout

  • WindowInfoTracker 添加了实验性非 activity 界面上下文支持。
  • WindowMetricsCalculator 添加了实验性非 activity 界面上下文。

迁移步骤

  • 如需启用 activity 嵌入功能,以在分屏中显示 activity,应用必须将 PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED 属性添加到清单 <application> 标记中:xml <property android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED" android:value="true" />。这样一来,系统就可以提前优化应用的分屏行为。
  • SplitInfo 分屏比
    • 检查当前分屏是否堆叠:kotlin SplitInfo.splitAttributes.splitType is SplitAttributes.SplitType.ExpandContainersSplitType
    • 检查当前分屏比:kotlin if (SplitInfo.splitAttributes.splitType is SplitAttributes.SplitType.RatioSplitType) { val ratio = splitInfo.splitAttributes.splitType.ratio } else { // Ratio is meaningless for other types. }
  • SplitController 迁移:
    • SplitController.getInstance() 更改为 SplitController.getInstance(Context)
    • SplitController.initialize(Context, @ResId int) 更改为 RuleController.getInstance(Context).setRules(RuleController.parse(Context, @ResId int))
    • SplitController.getInstance().isActivityEmbedded(Activity) 更改为 ActivityEmbeddingController.getInstance(Context).isActivityEmbedded(Activity)
    • SplitController.getInstance().registerRule(rule) 更改为 RuleController.getInstance(Context).addRule(rule)
    • SplitController.getInstance().unregisterRule(rule) 更改为 RuleController.getInstance(Context).removeRule(rule)
    • SplitController.getInstance().clearRegisteredRules() 更改为 RuleController.getInstance(Context).clearRules()
    • SplitController.getInstance().getSplitRules() 更改为 RuleController.getInstance(Context).getRules()
  • SplitRule 属性迁移:
    • minWidthminSmallestWidth 现在使用 dp 单位,而不是像素。应用可以使用以下调用:kotlin TypedValue.applyDimension( COMPLEX_UNIT_DIP, minWidthInPixels, resources.displayMetrics ),也可以直接将以像素为单位的 minWith 除以 displayMetrics#density
  • 必须将完成行为常量迁移到 FinishBehavior 类枚举类常量:
    • FINISH_NEVER 更改为 FinishBehavior.NEVER
    • FINISH_ALWAYS 更改为 FinishBehavior.ALWAYS
    • FINISH_ADJACENT 更改为 FinishBehavior.ADJACENT
  • 必须将布局方向迁移到 SplitAttributes.LayoutDirection
    • ltr 更改为 SplitAttributes.LayoutDirection.LEFT_TO_RIGHT
    • rtl 更改为 SplitAttributes.LayoutDirection.RIGHT_TO_LEFT
    • locale 更改为 SplitAttributes.LayoutDirection.LOCALE
    • 必须将 splitRatio 迁移到 SplitAttributes.SplitType.ratio(splitRatio)
  • SplitPairRule.Builder 迁移:
    • SplitPairRule.Builder(filters, minWidth, minSmallestWidth) 更改为 kotlin SplitPairRule.Builder(filters) .setMinWidthDp(minWidthInDp) // Optional if minWidthInDp is 600. .setMinSmallestWidthDp(minSmallestWidthDp) // Optional if minSmallestWidthInDp is 600.
    • setLayoutDirection(layoutDirection)setSplitRatio(ratio) 更改为 kotlin setDefaultSplitAttributes( SplitAttributes.Builder() .setLayoutDirection(layoutDirection) .setSplitType(SplitAttributes.SplitType.ratio(ratio)) .build() )
    • setFinishPrimaryWithSecondarysetFinishSecondaryWithPrimary 可接受 FinishBehavior 类枚举常量。请参阅“SplitRule 迁移”了解详情。
    • 使用 setMaxAspectRatioInPortrait(EmbeddingAspectRatio.ALWAYS_ALLOW),以在纵向设备上显示分屏。
  • SplitPlaceholder.Builder 迁移:
    • 只保留 filtersplaceholderIntent 参数。其他属性均移至 setter。请参阅“SplitPairRule.Builder 迁移”了解详情。
    • setFinishPrimaryWithPlaceholder 可接受 FinishBehavior 类枚举常量。请参阅“SplitRule 迁移”了解详情。
    • setLayoutDirection(layoutDirection)setSplitRatio(ratio) 更改为 kotlin setDefaultSplitAttributes( SplitAttributes.Builder() .setLayoutDirection(layoutDirection) .setSplitType(SplitAttributes.SplitType.ratio(ratio)) .build() )
    • 使用 setMaxAspectRatioInPortrait(EmbeddingAspectRatio.ALWAYS_ALLOW),以在纵向设备上显示分屏。

版本 1.1.0-rc01

2023 年 5 月 10 日

发布了 androidx.window:window-*:1.1.0-rc01版本 1.1.0-rc01 中包含这些提交内容。

新功能

  • ActivityEmbedding 作为稳定版 API 发布。
  • 修复了各种 bug。

版本 1.1.0-beta02

2023 年 4 月 5 日

发布了 androidx.window:window-*:1.1.0-beta02版本 1.1.0-beta02 中包含这些提交内容

新功能

  • 进行了内部修复和清理。

版本 1.1.0-beta01

2023 年 3 月 22 日

发布了 androidx.window:window-*:1.1.0-beta01版本 1.1.0-beta01 中包含这些提交内容。

activity 嵌入

  • 添加了 PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED,并将其作为应用清单中 <application> 标记的布尔属性。
  • 废弃了 isSplitSupported 并代之以 splitSupportStatus,以详细说明分屏功能不可用的原因。
  • 添加了 SplitController.SplitSupportStatus 嵌套类,以为 splitSupportStatus 属性提供状态常量。
  • SplitController 重构为了几个模块:
    • ActivityEmbeddingController 模块,适用于 ActivityActivityStack 相关 API。
    • isActivityEmbeddedSplitController 移动到了 ActivityEmbeddingController
    • RuleController 模块,用于完成 EmbeddingRule 相关操作:
    • 移除了 SplitController API:
      • clearRegisteredRules()
      • getSplitRules()
      • initialize()
      • registerRule()
      • unregisterRule()
    • 添加了 RuleController API:
      • addRule() - 添加规则或更新具有相同标记的规则。
      • removeRule() - 从已注册规则集合中移除规则。
      • setRules() - 建立规则集合。
      • clearRules() - 移除所有已注册规则。
      • `parseRules() - 根据 XML 规则定义解析规则。
  • 所有模块都需要通过 #getInstance() 方法初始化上下文,包括:
    • ActivityEmbeddingController#getInstance(Context)
    • SplitController#getInstance(Context)
    • RuleController#getInstance(Context)
  • 添加了 EmbeddingAspectRatio 类,以定义与显示宽高比相关的枚举类行为常量。
  • 添加了 SplitAttributes 类,以定义分屏布局。
  • SplitController 中添加了 SplitAttributes 计算器函数,以自定义分屏布局:
    • setSplitAttributesCalculator(Function)
    • clearSplitAttributesCalculator()
    • isSplitAttributesCalculatorSupported(),用于检查设备是否支持 SplitAttributesCalculator API
  • 添加了 EmbeddingRule#tag 字段。
  • SplitRule 中的 API 更新:
    • 添加了 defaultSplitAttributes,用于定义分屏的默认分屏布局;替换了 splitRatiolayoutDirection
    • defaultSplitAttributes 中添加了 XML 属性 splitRatiosplitLayoutDirection 的转换结果。
    • 更改了最小尺寸的定义,以使用密度无关像素 (dp) 而不是像素。
    • 添加了 minHeightDp,并将默认值设为 600dp。
    • minWidth 变更为了 minWidthDp,并将默认值设为 600dp。
    • minSmallestWidth 变更为了 minSmallestWidthDp,并将默认值设为 600dp。
    • 添加了 maxAspectRatioInHorizontal,并将默认值设为 ALWAYS_ALLOW
    • 添加了 maxAspectRatioInPortrait,并将默认值设为 1.4
    • 定义了 FinishBehavior 嵌套类,用以替换完成行为常量。
    • 将属性更改应用到了 SplitPairRuleSplitPlaceholderRuleBuilder 嵌套类。
  • SplitInfo#getSplitRatio() 替换成了 SplitInfo#getSplitAttributes(),以提供更多的分屏相关信息。

WindowLayout

  • WindowInfoTracker 添加了非 activity 界面上下文支持。
  • WindowMetricsCalculator 添加了非 activity 界面上下文。

迁移步骤

  • 如需启用 activity 嵌入功能,以在分屏中显示 activity,应用必须将 PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED 属性添加到清单 <application> 标记中:xml <property android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED" android:value="true" />。这样一来,系统就可以提前优化应用的分屏行为。
  • SplitInfo 分屏比
    • 检查当前分屏是否堆叠:kotlin SplitInfo.splitAttributes.splitType is SplitAttributes.SplitType.ExpandContainersSplitType
    • 检查当前分屏比:kotlin if (SplitInfo.splitAttributes.splitType is SplitAttributes.SplitType.RatioSplitType) { val ratio = splitInfo.splitAttributes.splitType.ratio } else { // Ratio is meaningless for other types. }
  • SplitController 迁移:
    • SplitController.getInstance() 更改为 SplitController.getInstance(Context)
    • SplitController.initialize(Context, @ResId int) 更改为 RuleController.getInstance(Context).setRules(RuleController.parse(Context, @ResId int))
    • SplitController.getInstance().isActivityEmbedded(Activity) 更改为 ActivityEmbeddingController.getInstance(Context).isActivityEmbedded(Activity)
    • SplitController.getInstance().registerRule(rule) 更改为 RuleController.getInstance(Context).addRule(rule)
    • SplitController.getInstance().unregisterRule(rule) 更改为 RuleController.getInstance(Context).removeRule(rule)
    • SplitController.getInstance().clearRegisteredRules() 更改为 RuleController.getInstance(Context).clearRules()
    • SplitController.getInstance().getSplitRules() 更改为 RuleController.getInstance(Context).getRules()
  • SplitRule 属性迁移:
    • minWidthminSmallestWidth 现在使用 dp 单位,而不是像素。应用可以使用以下调用:kotlin TypedValue.applyDimension( COMPLEX_UNIT_DIP, minWidthInPixels, resources.displayMetrics ),也可以直接将以像素为单位的 minWith 除以 displayMetrics#density
  • 必须将完成行为常量迁移到 FinishBehavior 类枚举类常量:
    • FINISH_NEVER 更改为 FinishBehavior.NEVER
    • FINISH_ALWAYS 更改为 FinishBehavior.ALWAYS
    • FINISH_ADJACENT 更改为 FinishBehavior.ADJACENT
  • 必须将布局方向迁移到 SplitAttributes.LayoutDirection
    • ltr 更改为 SplitAttributes.LayoutDirection.LEFT_TO_RIGHT
    • rtl 更改为 SplitAttributes.LayoutDirection.RIGHT_TO_LEFT
    • locale 更改为 SplitAttributes.LayoutDirection.LOCALE
    • 必须将 splitRatio 迁移到 SplitAttributes.SplitType.ratio(splitRatio)
  • SplitPairRule.Builder 迁移:
    • SplitPairRule.Builder(filters, minWidth, minSmallestWidth) 更改为 kotlin SplitPairRule.Builder(filters) .setMinWidthDp(minWidthInDp) // Optional if minWidthInDp is 600. .setMinSmallestWidthDp(minSmallestWidthDp) // Optional if minSmallestWidthInDp is 600.
    • setLayoutDirection(layoutDirection)setSplitRatio(ratio) 更改为 kotlin setDefaultSplitAttributes( SplitAttributes.Builder() .setLayoutDirection(layoutDirection) .setSplitType(SplitAttributes.SplitType.ratio(ratio)) .build() )
    • setFinishPrimaryWithSecondarysetFinishSecondaryWithPrimary 可接受 FinishBehavior 类枚举常量。请参阅“SplitRule 迁移”了解详情。
    • 使用 setMaxAspectRatioInPortrait(EmbeddingAspectRatio.ALWAYS_ALLOW),以在纵向设备上显示分屏。
  • SplitPlaceholder.Builder 迁移:
    • 只保留 filtersplaceholderIntent 参数。其他属性均移至 setter。请参阅“SplitPairRule.Builder 迁移”了解详情。
    • setFinishPrimaryWithPlaceholder 可接受 FinishBehavior 类枚举常量。请参阅“SplitRule 迁移”了解详情。
    • setLayoutDirection(layoutDirection)setSplitRatio(ratio) 更改为 kotlin setDefaultSplitAttributes( SplitAttributes.Builder() .setLayoutDirection(layoutDirection) .setSplitType(SplitAttributes.SplitType.ratio(ratio)) .build() )
    • 使用 setMaxAspectRatioInPortrait(EmbeddingAspectRatio.ALWAYS_ALLOW),以在纵向设备上显示分屏。

版本 1.1.0-alpha06

2023 年 2 月 22 日

发布了 androidx.window:window-*:1.1.0-alpha06版本 1.1.0-alpha06 中包含这些提交内容

新功能

  • 公开了从界面上下文获取 WindowLayoutInfo 的实验性版本。

API 变更

  • 添加了 splitSupportStatus,以指明 activity 嵌入功能是否可用。(I10024)
  • 将界面上下文 WindowLayoutInfo API 设为实验性。(I58ee0)
  • 引入了 WindowAreaController 和 API,使 RearDisplay 模式可将当前窗口移至与后置摄像头对齐的屏幕。(Iffcbf)
  • 更新了默认背景颜色。(I1ac1b)
  • 添加了 SplitAttributes 参数。(I18bdd)
  • SplitRuleSplitAttributesSplitAttributesCalculator 添加了 API。(I92d23)
  • 改进了与 maxAspectRatio 相关的 API:
    1. alwaysAllow()alwaysDisallow() 替换为 ALWAYS_ALLOWALWAYS_DISALLOW
    2. 将 @see 的 API 文档更新为独立文档。(I3057b)
  • 从公共 API 中移除了以下构造函数,因为它们不应由应用调用。
    • SplitInfo 构造函数
    • ActivityStack 构造函数 (Ide534)
  • SplitRule 现在接受 maxAspectRatioInPortrait/Landscape。它仅允许在父级边界的宽高比小于或等于请求的 maxAspectRatio 时进行 activity 分屏。(Ia5990)
  • RuleController#parseRules 更改为静态 (I785df)
  • 改进了与 ActivityEmbedding 相关的 API
    1. 采用一致的 API 命名方式 - 针对多个实例使用添加/移除功能:
    2. registerRule 更改为 addRule
    3. unregisterRule 更改为 removeRule
    4. getSplitRules 替换为 getRules,因为 ActivityRule 不是分屏规则
    5. 添加了 RuleController#setRules 以设置一系列规则
    6. 将与规则相关的 API 从 SplitController 提取到单例 RuleController。它们是:
    7. addRule
    8. removeRule
    9. getRules
    10. setRules
    11. clearRules
    12. parseRules
    13. #isActivityEmbeddedSplitController 提取到单例 ActivityEmbeddingController。它们是:
    14. isActivityEmbedded
    15. 移除了 SplitController#initialize。如需通过 XML 文件设置规则,请使用 RuleController#parseRules#setRules。在此变更生效之前:SplitController.initialize(context, R.xml.static_rules) 在此变更生效之后:val ruleController = RuleController.getInstance(context) val rules = ruleController.parseRules(R.xml.static_rules) ruleController.setRules(rules)
    16. 我们不再区分静态规则和运行时规则。也就是说,调用 #clearRules 会清除所有规则,无论它们使用静态 XML 规则定义注册,还是在运行时注册,都会被清除。若要让 SplitController#clearRegisteredRules 具有旧版行为,请使用 XML 资源 ID 调用 RuleController#parseRules,然后调用 RuleController#setRules 以重新设置规则。在此变更生效之前:SplitController.getInstance(context).clearRegisteredRules() 在此变更生效之后:val ruleController = RuleController.getInstance(context) val rules = ruleController.parseRules(R.xml.static_rules) ruleController.setRules(rules) (Ib3967)
  • 改进了 SplitRule API:
    1. 对于 SplitRule,以 DP 而不是像素为单位获取最小尺寸。
    2. 重构了 SplitRule 构建器,以将最小尺寸设置为可选。(I95f17)
  • 传递上下文以初始化 SplitController (I42549)
  • SplitRule#layoutDir 重命名为 #layoutDirection,将 SplitRule Builder#setLayoutDir 重命名为 Builder#setLayoutDirection。(I3f6d1)

版本 1.1.0-alpha04

2022 年 11 月 9 日

发布了 androidx.window:window-*:1.1.0-alpha04版本 1.1.0-alpha04 中包含这些提交内容

新功能

  • 公开了一种方法,用于确定 ActivityEmbeddingActivityStack 是否为空。
  • ActivityEmbedding API 中移除了实验性 API 标记。
  • 隐藏了 ActivityRule 构造函数,因为 Builder 是首选构造方式。
  • 添加了一种实验性方法,用于在 WindowMetrics 上获取 WindowInsets
  • 更新了 SplitPlaceholderFinishBehavior 以防止填充占位符。填充占位符会导致某种令人困惑的行为。

API 变更

  • 将 val isEmpty 设为公开,以替换 isEmpty 函数。
  • ActivityStack 参数 activity 重命名为 activitiesInProcess。(Ia5055)
  • 移除了 ActivityFilter#matchesClassNameActivityFilter#matchesClassNameOrWildCard,因为它们令人感到困惑。
  • 添加了 ActivityFilter#componentNameActivityFilter#intentAction,以允许调用方区分不同的过滤器 (I41f22)
  • 从实验性 API 中移除了 @Deprecated API (I216b3)
  • 移除了 Activity Embeding API 的 @ExperimentalWindowApi (I69ebe)
  • 隐藏了 ActivityRule 构造函数,改用构建器。(If4eb6)
  • 添加了 API,用于检查 activity 是否属于 ActivityFilter。(Ia43cf)
  • 更新了 API 文件以反映 WindowMetricsWindowMetricsCalculatorCompat 类中的更改 (I667fe)
  • 更新了 ActivityEmbedding 属性 Javadoc 和类名称 (Ia1386)
  • 添加了要在 AndroidManifest.xml 中使用的 ActivityEmbedding 属性标记名称 (Id1ad4)
  • 添加了新的 API SplitPlaceholderFinishBehaviorSplitPlaceholderRule.finishPrimaryWithPlaceholder,这取代了现有的 SplitPlaceholderRule.finishPrimaryWithSecondary,后者定义了占位符 activity 的完成时间以及 Activity Embedding 中关联 activity 的行为方式。(I64647)

bug 修复

  • 引入了 WindowAreaController 和 API,使 RearDisplay 模式可将当前窗口移至与后置摄像头对齐的屏幕。(I388ab)

版本 1.1.0-alpha03

2022 年 7 月 27 日

发布了 androidx.window:window-*:1.1.0-alpha03版本 1.1.0-alpha03 中包含这些提交内容

新功能

  • 更新了嵌入规则的默认值。

API 变更

  • 更新了嵌入规则属性的默认值。(Ic4d35)

版本 1.1.0-alpha02

2022 年 5 月 11 日

发布了 androidx.window:window-*:1.1.0-alpha02版本 1.1.0-alpha02 中包含这些提交内容

新功能

  • 发布了适配器库以支持 Java 和 RxJava。

版本 1.1.0-alpha01

2022 年 5 月 11 日

发布了 androidx.window:window-*:1.1.0-alpha01版本 1.1.0-alpha01 中包含这些提交内容

新功能

  • 发布了适配器以支持 java 和 RxJava

版本 1.1.0-alpha01

2022 年 4 月 20 日

发布了 androidx.window:window:1.1.0-alpha01版本 1.1.0-alpha01 中包含这些提交内容

新功能

  • 修复了以下 bug:将应用置于后台后,系统不再触发折叠功能。
  • 扩展了实验性 ActivityEmbedding API。

API 变更

  • 添加了用于检查是否正在嵌入 activity 的公共 API。(I39eb7)

bug 修复

  • 添加了可在 activity 分屏中自定义容器结束行为的 API (I1a1e4)
  • 为 activity 分屏规则添加了新的配置选项。(Iec6af)

版本 1.0

版本 1.0.0

2022 年 1 月 26 日

发布了 androidx.window:window-*:1.0.0版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

  • 通过 WindowInfoTrackerFoldingFeature 支持折叠手机。添加了有助于计算当前 WindowMetrics 的 WindowMetricsCalculator

版本 1.0.0-rc01

2021 年 12 月 15 日

发布了 androidx.window:window-*:1.0.0-rc01版本 1.0.0-rc01 中包含这些提交内容

新功能

  • 通过 WindowInfoTracker 添加了对可折叠手机的支持。
  • 添加了一些方法,以便计算当前和最大 WindowMetrics
  • 添加了一些辅助性测试 API。

版本 1.0.0-beta04

2021 年 11 月 17 日

发布了 androidx.window:window-*:1.0.0-beta04版本 1.0.0-beta04 中包含这些提交内容

新功能

  • 将 WindowInfoRepository 重命名为 WindowInfoTracker。
  • 将 activity 设置为 WindowInfoTracker 的一个显式方法依赖项。
  • 为 WindowMetricsCalculator 添加一个简单的 TestRule,用于为使用 Robolectric 的开发者提供支持。

API 变更

  • 提取扩展 (I25a5f)
  • 在 ActivityStack 中添加了 isEmpty (I5a4e6)
  • 将 WindowInfoRepository 重命名为 WindowInfoTracker。
    • 同时根据这项更改更新了 java/rxjava/testing 依赖项。(I0da63)
  • 为简单的 WindowMetricsCalculator 添加了测试规则。(Ibacdb)

版本 1.0.0-beta03

2021 年 10 月 27 日

发布了 androidx.window:window-*:1.0.0-beta03版本 1.0.0-beta03 中包含这些提交内容

新功能

  • 添加了实验性 Activity Embeding API。此初始布局版本可以并排显示两个 Activity。

API 变更

  • 移除了 currentWindowMetrics API,因为我们无法准确提供。请改用 WindowMetricsCalculator (Icda5f)
  • 更新了 Extensions API。(Ica92b)
  • 为一项新功能添加了一个接口,该接口允许嵌入 activity 并在父级任务窗口中并排显示这些 activity。(I5711d)
  • 已隐藏 WindowMetrics 和 WindowLayoutInfo 的构造函数,请改用测试 API。(I5a1b5)
  • 添加了一个 API,用于创建虚假 WindowLayoutInfo 对象。(I4a2fd)

bug 修复

版本 1.0.0-beta02

2021 年 9 月 1 日

发布了 androidx.window:window-*:1.0.0-beta02版本 1.0.0-beta02 中包含这些提交内容

新功能

  • 添加了实验性注解,以便为实验性 API 添加注解。(I9f1b6)
  • 添加了测试方法来创建接受 Rect 的测试 FoldingFeature,以便在使用 Robolectric(而非实际 activity)时更轻松地进行测试。(Id1cca)

版本 1.0.0-beta01

2021 年 8 月 18 日

发布了 androidx.window:window-*:1.0.0-beta01版本 1.0.0-beta01 中包含这些提交内容

新功能

  • 移除了旧常量,并将 FoldingFeature 转换为一个接口。

API 变更

  • 移除了旧常量,并将 FoldFeature 转换为一个接口。(I9a2d5)

bug 修复

  • 依赖于 Test Core 库的库已升级到版本 1.4.0,现支持 Android 平台版本 S。(I88b72b/189353863

版本 1.0.0-alpha10

2021 年 8 月 4 日

发布了 androidx.window:window-*:1.0.0-alpha10版本 1.0.0-alpha10 中包含这些提交内容

新功能

  • 将 WindowInfoRepo 重命名为了 WindowInfoRepository,并调整了相应的类/文件。
  • 在 WindowInfoRepository 中将当前窗口指标转换为了 Flow,因为该值会随时间而变化。
  • 将 WindowInfoRepoJavaAdapter 重命名为了 WindowInfoRepoCallbackAdapter
  • 添加了辅助方法来创建测试 FoldingFeature 对象
  • 更新了软件包,以便按软件包支持的功能对类进行分组。

API 变更

  • 将 ActivityExt 重命名为了 ActivityExtensions,并将 Repo 更改为了 Repository。(I61a16)
  • 更新了类的软件包。(I23ae2)
  • 从 WindowInfoRepo 中移除了 WindowMetrics (I24663)
  • 移除了 WindowManager 并改用 WindowInfoRepo
    • 将 WindowBackend 转换为了内部类。(I06d9a)
  • 将窗口指标转换为了 Flow。
    • 将 Java 适配器重命名为了 WindowInfoRepoCallbackAdapter
    • 移除了 callbackFlow,不再使用实验性 API。(Ia4d15)
  • 添加了辅助方法来创建测试显示功能。
    • 从 occlusionMode 更改为了 occlusionType (If4cff)

bug 修复

  • 修复了移除 core 库时出现的 proguard 错误。
  • 修复了 WindowLayoutInfo 未能传递给其他订阅者的错误。
  • 修复了配置更改不会触发折叠功能更新的错误。

版本 1.0.0-alpha09

2021 年 6 月 30 日

发布了 androidx.window:window-*:1.0.0-alpha09版本 1.0.0-alpha09 中包含这些提交内容

新功能

  • 将整数常量更改为无界限枚举。
  • 添加测试 util 以创建测试折叠功能。

API 变更

  • 添加了辅助方法来创建测试显示功能。(I3cf54)
    • occlusionMode 更改为 occlusionType

bug 修复

  • 当添加数据流的多个使用方时,发出初始值。

版本 1.0.0-alpha08

2021 年 6 月 16 日

发布了 androidx.window:window-*:1.0.0-alpha08版本 1.0.0-alpha08 中包含这些提交内容

新功能

  • 发布了测试工件,以便在使用 WindowInfoRepository 时更轻松地进行测试。使用 WindowInfoRepository 可获取有关 DisplayFeature 和 WindowMetrics 的信息。(I57f66Ida620

版本 1.0.0-alpha07

2021 年 6 月 2 日

发布了 androidx.window:window-*:1.0.0-alpha07版本 1.0.0-alpha07 中包含这些提交内容

新功能

  • 将核心窗口库迁移到了 Kotlin。今后将使用协程和挂起函数来公开异步数据。
  • 将 WindowInfoRepo 添加为用于获取 WindowLayoutInfo 数据流和 WindowMetrics 的主交互点。
  • 新增了 window-java 工件,可提供兼容 Java 的 API,用于注册和取消注册回调。
  • 新增了 window-rxjava2window-rxjava3 工件,可提供适配 RxJava 的 API。

API 变更

  • 添加了 WindowServices,以统一提供依赖项。
    • 添加了基于协程的 API,以使用窗口布局信息。(Iab70f)
  • 将核心窗口管理器库迁移到了 Kotlin。(Icca34)

bug 修复

  • 添加了新的数据类,以表示功能边界。(I6dcd1)

版本 1.0.0-alpha06

2021 年 5 月 5 日

发布了 androidx.window:window:1.0.0-alpha06版本 1.0.0-alpha06 中包含这些提交内容

新功能

  • 我们已开始迁移到 Kotlin,并将在下一版本中完成迁移。
  • DeviceState 已从公共 API 中移除,请改用 FoldingFeature。
  • 我们已从 FoldingFeature 状态中移除了 STATE_FLIPPED,因为目前任何用例都不支持它。
  • 此外,我们还移除了其他已废弃的 API。

API 变更

  • 添加 Kotlin 作为依赖项。
    • 将核心库迁移到 Kotlin。(Idd995)
  • 移除了 DisplayFeature 构建器。(I61fa4)
  • 从公共 API 中移除了 DeviceState,请改用 FoldingFeature。(Id6079)
  • 从扩展程序中移除了设备状态回调。(I5ea83)
  • 从 FoldingFeature 中移除了 STATE_FLIPPED。(I9c4e1)
  • 移除了已废弃的注册方法。(Ib381b)

版本 1.0.0-alpha05

2021 年 3 月 24 日

发布了 androidx.window:window:1.0.0-alpha05版本 1.0.0-alpha05 中包含这些提交内容。

新功能

我们为 FoldingFeature 添加了一些便捷方法,以便应用能够判断相应功能是否处于分离状态、遮蔽状态,以及确定合页的朝向。我们还将隐藏合页类型,以便

我们从 WindowManager 中移除同步读取方法。因存在隐式竞态条件,同步读取方法容易出错。注册监听器和回调,以在 WindowLayoutInfo 上接收更新。

API 变更

  • 添加了可与 FoldingFeature 搭配使用的便捷方法 (Ie733f)
  • 从 WindowManager 中移除了同步读取方法 (I96fd4)

版本 1.0.0-alpha04

2021 年 3 月 10 日

发布了 androidx.window:window:1.0.0-alpha04版本 1.0.0-alpha04 中包含这些提交内容

新功能

  • 修复了在没有 OEM 实现的情况下不发出 WindowLayoutInfo 的错误。现在我们会发出一个空的 WIndodoLayoutInfo。
  • 修复了因铰链状态在应用处于后台运行时发生更改而导致系统无法正确更新状态的错误。现在状态将会保持一致。
  • 更新了 proguard 文件,以忽略运行时依赖项发出的警告。

bug 修复

  • 当缺少 OEM 库时,发出一个空值。(Ide935)

版本 1.0.0-alpha03

2021 年 2 月 18 日

发布了 androidx.window:window:1.0.0-alpha03版本 1.0.0-alpha03 中包含这些提交内容

新功能

  • 当 OEM 实现为空时,针对 WindowLayoutInfo 发出一个空值。这样可以更轻松地在更多设备上使用此库。由于这些 API 是异步的,因此我们仍建议应用编写一些防御性代码,并在超时后发出默认值。我们对 OEM 实现不作任何保证,并且初始值也可能会出现延迟。

bug 修复

  • 当缺少 OEM 库时,发出一个空值。(Ide935)

版本 1.0.0-alpha02

2021 年 1 月 27 日

发布了 androidx.window:window:1.0.0-alpha02版本 1.0.0-alpha02 中包含这些提交内容

新功能

  • 我们废弃了一些 API,以帮助简化 API 并减少错误。一些值得注意的示例包括从 WindowManager 中移除同步读取操作,以及废弃 DeviceState。同步读取操作可能会导致出现竞态条件并且界面错误。

  • 我们已将 DisplayFeature 转换为一个今后将实现其他功能的接口。我们的第一个功能是 FoldingFeature,现在是屏幕折叠或合页的表示形式。该部分还包含取代 DeviceState 的合页的状态。

  • Android 11 中引入了 WindowMetrics,可让开发者轻松查询与窗口相关的指标,例如,窗口的位置和大小,以及任何系统边衬区。我们在此版本中向后移植了 API,以便开发者能够利用 WindowMetrics,并继续支持旧版 Android。可以通过 WindowManager#getCurrentWindowMetrics() 和 WindowManager#getMaximumWindowMetrics() API 获取 WindowMetrics。

API 变更

  • 废弃将在下一个 Alpha 版中移除的 API (Ib7cc4)
  • 更新 ExtensionInterface 以接受显式 Activity 引用。(I07ded)
  • 引入 WindowMetrics API。(I3ccee)
  • 从 WindowManager 中移除同步读取方法 (I69983)
  • 保护 ExtensionWindowBackend 软件包。(Ied208)

bug 修复

  • 更新 ExtensionInterface API 以接受视觉上下文。(I8e827)

外部贡献

  • 合并 DeviceState 和 WindowLayoutInfo,以便更轻松地访问数据。(Id34f4)

版本 1.0.0-alpha01

2020 年 2 月 27 日

发布了 androidx.window:window:1.0.0-alpha01androidx.window:window-extensions:1.0.0-alpha01版本 1.0.0-alpha01 中包含这些提交内容 这是 Window Manager 库的第一个版本。

新功能

  • DisplayFeature:这一新的 API 可识别一整块屏幕平面上的中断处,比如合页或折叠线
  • DeviceState:这一新的 API 可根据定义的折叠状态(例如 CLOSEDOPENEDHALF_OPENED 等)列表,提供手机当前的折叠状态