WindowManager 扩展程序

使用集合保持井井有条 根据您的偏好保存内容并对其进行分类。

Jetpack WindowManager 库让应用开发者能够支持新的设备外形规格和多窗口环境。

WindowManager 扩展程序（Extensions）是一个可选的 Android 平台模块，支持各种 Jetpack WindowManager 功能。该模块在 AOSP 中以 frameworks/base/libs/WindowManager/Jetpack 实现，并在支持 WindowManager 功能的设备上发布。

Extensions 模块分发

如果设备 makefile 中启用了 Extensions，则 Extensions 会编译到 .jar 库中，并放置在设备上的 system_ext 分区中。

要在设备上启用 Extensions，请将以下内容添加到产品设备 makefile 中

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

这会在设备上启用 androidx.window.extensions 和 androidx.window.sidecar 软件包，并设置 persist.wm.extensions.enabled 属性。在 makefile 中包含这些软件包也会在 etc/permissions/ 中放置声明，使其可供应用进程使用。通常，当 Jetpack WindowManager 库使用这些模块时，这些模块会在运行时加载到应用进程中并作为应用进程的一部分执行，这使其操作类似于客户端框架代码，如下图所示

androidx.window.extensions 模块是当前正在积极开发的 Extensions 模块。androidx.window.sidecar 模块是为兼容最早版本的 Jetpack WindowManager 而包含的旧版模块，但 Sidecar 不再积极维护。

下图显示了确定使用 androidx.window.extensions 还是 androidx.window.sidecar 的逻辑。

Extensions 模块

Extensions 为可折叠大屏幕设备和支持外部显示屏窗口化的设备提供窗口化功能。功能领域包括：

• Activity 嵌入
• 窗口布局信息
• 窗口区域

除非 兼容性定义文档 (CDD) 7.1.1.1 中明确请求该功能，否则如果设备硬件不支持相应功能，Extensions 的 OEM 实现可以提供空组件或具有 WindowExtensions 接口中方法的默认或存根实现的组件。

Extensions 和 Jetpack API

除了公共平台 API 之外，WindowManager Extensions 模块还提供自己的 API Surface。Extensions 模块在非开发者面向的 androidx.window.extensions Jetpack 库中公开开发，以便 Jetpack WindowManager (androidx.window) 可以在编译时链接到它。Extensions API Surface 通常提供更低级别的 API。

Extensions 提供的 API 仅供 Jetpack WindowManager 库使用。Extensions API 不供应用开发者直接调用。为了确保功能正常，请勿将 Extensions 库作为依赖项添加到 Gradle 构建文件中。避免直接将 Extensions 库预编译到应用中；而应依赖运行时加载，以防止加载预编译类和运行时提供的 Extensions 类混合的情况。

Jetpack WindowManager (androidx.window) 旨在作为应用依赖项添加，并提供面向公共开发者的 API，包括 WindowManager Extensions 功能的 API。WindowManager 库会自动将 Extensions 加载到应用进程中，并将较低级别的 Extensions API 封装到更高级别的抽象和更专注的接口中。WindowManager Jetpack API 遵循现代 Android 应用开发标准，旨在通过与其他 AndroidX 库良好集成来提供便捷的互操作性。

Extensions 版本和更新

Extensions 模块可以与 Android 平台一起按年度或季度更新。季度更新使 Extensions API 级别能够在 Android 平台 API 更新之间增加，从而实现更快的迭代，并为 OEM 提供机会，以便在硬件发布时添加对新功能的官方 API 访问。

下表列出了各种 Android 版本的 androidx.window.extensions API 版本。

每次现有稳定 API 表面（右列）增加时，Extensions API 级别（中间列）都会增加。

向前和向后兼容性

Jetpack WindowManager 负责处理频繁的 API 级别更新、快速的 API 演变以及向后兼容性的复杂性。当库代码在应用进程中执行时，库会检查声明的 Extensions API 级别，并根据声明的级别提供对功能的访问。

为了保护应用在运行时免于崩溃，WindowManager 还会根据声明的 Extensions API 级别对可用的 Extensions API 执行运行时 Java 反射检查。如果存在不匹配，WindowManager 可以禁用 Extensions 的使用（部分或完全禁用），并将相关功能报告为对应用不可用。

WindowManager Extensions 实现为 system_ext 模块，该模块使用私有平台 API 调用 WindowManager 核心、DeviceStateManager 以及 Extensions 功能实现中的其他系统服务。

在相应的季度或年度 Android 平台版本（版本最终确定）之前，与 Extensions 预发布版本的兼容性可能无法保持。Extensions API 的完整历史记录可以在发布分支 window:extensions:extensions API 文本文件中找到。

较新版本的 Extensions 必须继续与编译到应用中的旧版本 WindowManager 配合使用，以保持向前兼容性。为了确保这一点，任何新版本的 Extensions API 都只会添加新 API，而不会删除旧 API。因此，具有旧版本 WindowManager 的应用可以继续使用应用编译时所针对的旧版本 Extensions API。

CTS 验证确保对于设备上声明的任何 Extensions API 版本，该版本和之前版本的所有 API 都存在且功能正常。

性能

默认情况下，从 Android 14（API 级别 34）开始，Extensions 模块缓存在非引导类路径系统类加载器中，因此在应用启动时将模块加载到内存中不会对性能产生影响。当客户端和服务器之间执行额外的 IPC 调用时，使用各个模块功能可能会对应用的性能特征产生轻微影响。

模块

Activity 嵌入

Activity Embedding 组件使应用能够针对大屏幕设备和外部显示器优化其 UI。Activity Embedding 支持在多窗格布局中并排显示两个 Activity，从而为旧版应用提供自适应应用开发便利。

Activity Embedding 组件必须在所有内置显示屏尺寸等于或大于 sw600dp 的设备上可用。Activity Embedding 还必须在支持外部显示器连接的设备上启用，因为当运行时连接外部显示器时，应用可能会以更大的尺寸显示。

设备配置

除了在Extensions 模块分发部分中描述的启用 Extensions 模块之外，不需要特定的设备配置。在所有支持多窗口模式的设备上启用 Extensions 模块是有意义的。未来的 Android 版本可能会要求在常见的手持设备和大屏幕设备配置上使用 Extensions 模块。

窗口布局信息

窗口布局信息组件标识可折叠设备上铰链的位置和状态，当铰链穿过应用窗口时。窗口布局信息使应用能够响应可折叠设备上的桌面模式并显示优化的布局。有关使用详情，请参阅让您的应用感知折叠。

包含连接独立或连续显示面板区域的铰链的可折叠 Android 设备必须通过 WindowLayoutComponent 向应用提供有关铰链的信息。

铰链位置和边界必须相对于传递到 API 的 Context 标识的应用窗口报告。如果应用窗口边界与铰链边界不相交，则不得报告铰链 DisplayFeature。当显示功能的位置可能无法可靠报告时，例如当应用窗口可以在多窗口模式或兼容性 Letterboxing 模式下由用户自由移动时，也可以不报告显示功能。

对于折叠功能，当铰链位置在稳定状态之间发生变化时，必须报告状态更新。默认情况下，在平面显示状态下，API 必须报告 FoldingFeature.State.FLAT。如果设备硬件可以以半折叠模式保持稳定状态，则 API 必须报告 FoldingFeature.State.HALF_OPENED。API 中没有闭合状态，因为在这种情况下，应用窗口要么不可见，要么不会与铰链边界相交。

设备配置

为了支持折叠功能实现，OEM 必须执行以下操作

• 在 device_state_configuration.xml 中配置设备状态，以供 DeviceStateManagerService 使用。有关参考，请参阅 DeviceStateProviderImpl.java。

  如果 DeviceStateProvider 或 DeviceStatePolicy 的默认实现不适合设备，则可以使用自定义实现。

• 在Extensions 模块分发部分中描述的启用 Extensions 模块。

• 在 com.android.internal.R.string.config_display_features 字符串资源中（通常在设备叠加层中的 frameworks/base/core/res/res/values/config.xml 中）指定显示功能的位置。

  字符串的预期格式为

  <type>-[<left>,<top>,<right>,<bottom>]

  type 可以是 fold 或 hinge。left、top、right 和 bottom 的值是自然显示方向中显示坐标空间中的整数像素坐标。配置字符串可以包含多个以分号分隔的显示功能。

  例如

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• 定义 DeviceStateManager 中使用的内部设备状态标识符与在 com.android.internal.R.array.config_device_state_postures 中发送给开发者的公共状态常量之间的映射。

  每个条目的预期格式为

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  支持的状态标识符为

  • COMMON_STATE_NO_FOLDING_FEATURES = 1：该状态没有要报告的折叠功能。例如，它可以是典型内折叠设备的闭合状态，主屏幕位于内侧。
  • COMMON_STATE_HALF_OPENED = 2：折叠功能半打开。
  • COMMON_STATE_FLAT = 3：折叠功能平展。例如，它可以是典型内折叠设备的打开状态，主屏幕位于内侧。
  • COMMON_STATE_USE_BASE_STATE = 1000：在 Android 14 中，一个值，可用于模拟状态，其中铰链状态是使用基本状态导出的，如 CommonFoldingFeature.java 中所定义

  有关更多信息，请参阅 DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int)。

  例如

  <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
  <string-array name="config_device_state_postures" translatable="false">
    <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
    <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
    <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
    <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
    <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
  </string-array>
  

窗口区域

窗口区域组件提供了一组功能，使应用能够访问某些可折叠和多显示器设备上的其他显示器和显示区域。

后置显示器模式使应用能够在可折叠设备的副屏上显示相机预览 UI，从而允许使用主设备摄像头进行自拍和视频拍摄。具有与后置设备摄像头对齐的 Android 兼容（根据 Android CDD 在尺寸、密度和可用导航功能等属性方面的定义）副屏的设备必须提供对后置显示器模式的访问。

在 Android 14 上，双显示器模式使在可折叠设备内屏上运行的应用能够在面向其他用户的副屏上显示其他内容；例如，副屏可以向被拍照或录像的人显示相机预览。

设备配置

为了支持折叠功能实现，OEM 必须执行以下操作

• 在 device_state_configuration.xml 中配置设备状态，以供 DeviceStateManagerService 使用。有关更多信息，请参阅 DeviceStateProviderImpl.java。

  如果 DeviceStateProvider 或 DeviceStatePolicy 的默认实现不适合设备，则可以使用自定义实现。

• 对于支持打开或平面模式的可折叠设备，请在 com.android.internal.R.array.config_openDeviceStates 中指定相应的状态标识符。

• 对于支持折叠状态的内折叠设备，请在 com.android.internal.R.array.config_foldedDeviceStates 中列出相应的状态标识符。

• 对于支持半折叠状态（铰链像笔记本电脑一样半打开）的内折叠设备，请在 com.android.internal.R.array.config_halfFoldedDeviceStates 中列出相应的状态。

• 对于支持后置显示器模式的设备

  • 在 com.android.internal.R.array.config_rearDisplayDeviceStates 中为 DeviceStateManager 列出相应的状态。
  • 在 com.android.internal.R.string.config_rearDisplayPhysicalAddress 中指定后置显示器的物理显示地址。
  • 在 com.android.internal.R.integer.config_deviceStateRearDisplay 中指定供 Extensions 使用的状态标识符。
  • 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中添加状态标识符，以使其可供应用使用。

• 在 Android 14 上，对于支持双（并发）显示器模式的设备

  • 将 com.android.internal.R.bool.config_supportsConcurrentInternalDisplays 设置为 true。
  • 在 com.android.internal.R.config_deviceStateConcurrentRearDisplay 中指定后置显示器的物理显示地址。
  • 如果标识符旨在供应用使用，则在 com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay 中指定供 Extensions 使用的状态标识符。
  • 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中添加状态标识符，以使其可供应用使用。

验证

OEM 必须验证他们的实现，以确保常见场景中的预期行为。CTS 测试和使用 Jetpack WindowManager 的测试可供 OEM 用于测试实现。

CTS 测试

要运行 CTS 测试，请参阅运行 CTS 测试。与 Jetpack WindowManager 相关的 CTS 测试位于 cts/tests/framework/base/windowmanager/jetpack/ 下。测试模块名称为 CtsWindowManagerJetpackTestCases。

WindowManager 测试

要下载 Jetpack WindowManager 测试，请按照 Android Jetpack 说明进行操作。测试位于 window 库的 window:window 模块下：window/window/src/androidTest/。

要从命令行运行 window:window 模块的设备测试，请执行以下操作

1. 插入已启用开发者选项和 USB 调试的设备。
2. 允许计算机调试设备。
3. 在 androidx 存储库的根目录中打开一个 shell。
4. 将目录更改为 framework/support。
5. 运行以下命令：./gradlew window:window:connectedAndroidTest。
6. 分析结果。

要从 Android Studio 运行测试，请执行以下操作

1. 打开 Android Studio。
2. 插入已启用开发者选项和 USB 调试的设备。
3. 允许计算机调试设备。
4. 导航到 window 模块的 window 库中的测试。
5. 打开一个测试类，然后使用编辑器右侧的绿色箭头运行。

或者，您可以在 Android Studio 中创建一个配置来运行测试方法、测试类或模块中的所有测试。

可以通过查看 shell 的输出来手动分析结果。如果设备不满足某些假设，则会跳过某些测试。结果保存在标准位置，分析师可以编写脚本来自动分析结果。