WindowManager

代码示例 Codelab

API 参考文档
androidx.window
androidx.window.core
androidx.window.embed
androidx.window.layout
androidx.window.testing.layout

借助 Jetpack WindowManager 库，应用开发者可为新的设备外形规格和多窗口环境提供支持。该库为 API 版本 14 及更高版本提供通用的 API 接口。初始版本以可折叠设备为目标，不过未来版本将支持更多屏幕类型和窗口功能。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2023 年 2 月 22 日	1.0.0	-	-	1.1.0-alpha06

声明依赖项

如需添加 WindowManager 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

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

Groovy

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

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

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

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

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

Kotlin

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

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

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

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

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

反馈

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

创建新问题

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

版本 1.1

版本 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)
为 SplitRule、SplitAttributes 和 SplitAttributesCalculator 添加了 API。(I92d23)
改进了与 maxAspectRatio 相关的 API：
1. 将 alwaysAllow() 和 alwaysDisallow() 替换为 ALWAYS_ALLOW 和 ALWAYS_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. 将 #isActivityEmbedded 从 SplitController 提取到单例 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 中包含这些提交内容。

新功能

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

API 变更

将 val isEmpty 设为公开，以替换 isEmpty 函数。
将 ActivityStack 参数 activity 重命名为 activitiesInProcess。(Ia5055)
移除了 ActivityFilter#matchesClassName 和 ActivityFilter#matchesClassNameOrWildCard，因为它们令人感到困惑。
添加了 ActivityFilter#componentName 和 ActivityFilter#intentAction，以允许调用方区分不同的过滤器 (I41f22)
从实验性 API 中移除了 @Deprecated API (I216b3)
移除了 Activity Embeding API 的 @ExperimentalWindowApi (I69ebe)
隐藏了 ActivityRule 构造函数，改用构建器。(If4eb6)
添加了 API，用于检查 activity 是否属于 ActivityFilter。(Ia43cf)
更新了 API 文件以反映 WindowMetrics 和 WindowMetricsCalculatorCompat 类中的更改 (I667fe)
更新了 ActivityEmbedding 属性 Javadoc 和类名称 (Ia1386)
添加了要在 AndroidManifest.xml 中使用的 ActivityEmbedding 属性标记名称 (Id1ad4)
添加了新的 API SplitPlaceholderFinishBehavior 和 SplitPlaceholderRule.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 的主要功能

通过 WindowInfoTracker 和 FoldingFeature 支持折叠手机。添加了有助于计算当前 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 修复

修复了内存泄漏的问题。（I3fc79、b/202989046）

版本 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。（I88b72、b/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 的信息。（I57f66、Ida620）

版本 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-rxjava2 和 window-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-alpha01 和 androidx.window:window-extensions:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容这是 Window Manager 库的第一个版本。

新功能

DisplayFeature：这一新的 API 可识别一整块屏幕平面上的中断处，比如合页或折叠线
DeviceState：这一新的 API 可根据定义的折叠状态（例如 CLOSED、OPENED、HALF_OPENED 等）列表，提供手机当前的折叠状态