适用于 XR 的 Jetpack Compose

以声明方式构建空间 UI 布局，充分利用 Android XR 的空间能力。
最新更新 稳定版 发布候选版 Beta 发布 Alpha 发布
2025 年 5 月 7 日 - - - 1.0.0-alpha04

声明依赖项

要添加对 XR compose 的依赖项，你必须将 Google Maven 存储库添加到你的项目中。请阅读Google 的 Maven 存储库了解更多信息。

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

Groovy

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha04"

    // Use to write unit tests
    testImplementation "androidx.xr.compose:compose-testing:1.0.0-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha04")

    // Use to write unit tests
    testImplementation("androidx.xr.compose:compose-testing:1.0.0-alpha04")
}

有关依赖项的更多信息，请参阅添加构建依赖项。

反馈

你的反馈有助于 Jetpack 变得更好。如果你发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请先查看此库中现有问题。你可以点击星标按钮为现有问题投票。

创建新问题

有关更多信息，请参阅问题跟踪器文档。

版本 1.0

版本 1.0.0-alpha04

2025 年 5 月 7 日

androidx.xr.compose:compose:1.0.0-alpha04 和 androidx.xr.compose:compose-testing:1.0.0-alpha04 已发布。版本 1.0.0-alpha04 包含这些提交。

新功能

  • 添加了 CompositionLocalConsumerSubspaceModifierNode 接口，允许自定义 SubspaceModifier 类型访问组合局部值。
  • 添加了一个新的 SpatialPanel API，它遵循 Compose AndroidView 实现样式并弃用了之前的 ViewBased SpatialPanel。
  • 添加了 VolumeConstraints.Unbounded 伴生对象，表示无界约束。
  • 添加了 SubspaceModifier.onPointSourceParams 以允许空间化音频源。
  • 已添加公共 ApplicationSubspace，提供可选的 VolumeConstraints 来定义应用可渲染空间内容的 3D 区域。默认情况下，如果未指定约束，则子空间将由 SpatialUser 当前的视野宽度和高度进行限制。如果无法确定视野，用户可以提供要使用的约束。否则，将使用默认的视野宽度和高度值。
  • 添加了 SpatialExternalSurface，可用于渲染立体内容。SpatialExternalSurface 可通过修饰符（alpha 除外）和边缘羽化效果进行自定义。
  • 添加了一个新的 pointerHoverIcon 子空间修饰符，允许用户设置空间指针的图标。

API 变更

  • 移除了所有 Jetpack XR 软件包上的 RequiresApi(34) 限制。此限制是多余的，因为 Jetpack XR 目前仅适用于 API 级别 34+ 的设备。( Iae0f8 )
  • 用 Kotlin 2.0 发布的项目需要 KGP 2.0.0 或更高版本才能使用。( Idb6b5 )
  • 现在，不带嵌入式活动的 Spatial 面板将支持返回处理。为了使返回处理起作用，你需要在 Android 清单中指定 android:enableOnBackInvokedCallback="true"。
  • 现在，Spatial 对话框将支持返回处理。为了使返回处理起作用，你需要在 Android 清单中指定 android:enableOnBackInvokedCallback="true"。
  • 基于 Compose 和基于 View 的 SpatialPanel 现在可以根据其内容调整大小。
  • 开发者现在可以设置自己的自定义 SpatialElevationLevel 值，并且不受预定义级别的限制。
  • 现在可以通过 elevation 参数自定义 Orbiter 高度级别。
  • 默认情况下，子空间现在可以由 SpatialUser 的视野宽度和高度进行限制。如果无法确定视野，则使用默认视野宽度和高度值。
  • 向 Movable 修饰符添加了新的回调 onMoveStart 和 onMoveEnd。onMoveStart 和 onMoveEnd 回调在用户开始和结束使用可移动修饰符移动子空间可组合项时调用。
  • 已从 SpatialRow 和 SpatialPanel 等空间 API 中移除了 name 参数。对于调试空间 Compose 树，请改用 SubspaceModifier.testTag。
  • 移除了一个不支持的 SpatialPopup 重载，该重载仅包含 spatialElevationLevel 和 content。请使用支持 onDimissRequest 的接口。
  • 已移除 Movable 修饰符中的 onPoseChange 回调。请改用 onMove。
  • SubspaceModifiers 如果已分离或正在分离，将不再应用其效果。
  • 现有的 SpatialRow API 已拆分为 SpatialRow 和 SpatialCurvedRow。如果之前使用 SpatialRow 的 curveRadius 参数，现在请改用提供相同行为的 SpatialCurvedRow。
  • 在相似的最新系统映像上运行时，MainPanel 和 ActivityPanel 不再具有标题栏。
  • Alpha 和缩放修饰符现在可以堆叠，它们的值将相乘，以获得最终应用的 Alpha 或缩放值。
  • Movable 修饰符中的 onPoseChange 回调已优化，以实现更平滑的姿态移动。
  • 可移动和可调整大小的修饰符现在将在主线程上执行其回调，以确保状态更改将触发重新组合。
  • 在布局和测量阶段添加了状态观察，以确保 SubspaceLayout 中的状态更改将触发重新布局。
  • 优化了修饰符链更新，以更好地重用现有修饰符。

Bug 修复

  • 显示 SpatialDialog 时停止遮罩。( Ic4594 )
  • 现在，在修饰符节点分离时发出的重新布局请求将被忽略。
  • 移除了由 Movable 和 Resizable 修饰符触发的重新布局阶段。
  • 修复了 MainPanel() 可组合项中发生的崩溃，该崩溃发生在尺寸设置为零时，无论是直接设置还是在布局计算期间（例如，SpatialRow/SpatialColumn 计算）。面板现在将被隐藏。请注意，此修复专门解决了布局阶段的崩溃；通过用户交互将面板大小调整为零将单独处理。隐藏的面板缺少 UI 可供性。
  • 修复了可调整大小修饰符中 maintainAspectRatio 的问题。现在应该保持纵横比。
  • 修复了嵌套子空间的问题，即它们在单帧中定位不正确。
  • 修复了应该应用圆角时有时未应用的问题。
  • NestedSubspaces 将不再在错误位置出现一帧。

版本 1.0.0-alpha03

2025 年 2 月 26 日

androidx.xr.compose:compose:1.0.0-alpha03 和 androidx.xr.compose:compose-testing:1.0.0-alpha03 已发布，自上次 alpha 版本以来没有显著变化。版本 1.0.0-alpha03 包含这些提交

版本 1.0.0-alpha02

2025 年 2 月 12 日

androidx.xr.compose:compose:1.0.0-alpha02 和 androidx.xr.compose:compose-testing:1.0.0-alpha02 已发布。版本 1.0.0-alpha02 包含这些提交。

新功能

  • 现在，当 Spatial Dialog 被激活时，Activity Panel 可以为其内容添加遮罩。
  • Orbiter API 现在可在 SubspaceComposable 上下文中使用，并将 Orbiter 附加到其最近的基于 SubspaceLayout 的可组合父级。
  • 引入了 LayoutCoordinatesAwareModifierNode 以允许自定义基于位置的修饰符。
  • 向 SubspaceModifier.Node 添加了 attach/detach 生命周期方法。
  • 向可移动修饰符添加了 scaleWithDistance。当启用 scaleWithDistance 时，移动的子空间元素将增长或缩小。它还将保持移动前拥有的任何显式缩放。

API 变更

  • 已移除 SessionCallbackProvider，转而使用 SpatialCapabilities。

其他变更

  • 将 minSDK 降低到 24。所有 Jetpack XR API 在运行时仍需要 API 34。
  • Orbiter EdgeOffset.inner、EdgeOffset.outer 和 EdgeOffset.overlap 构造函数不再是 @Composable 方法，这使得它们可以在非可组合上下文中使用。
  • 更新空间高程级别以匹配最新的 UX 规范。
  • 在 MeasurableLayout 中实现 SubspaceSemanticsInfo 接口。
  • 将 SubspaceModifierElement 重命名为 SubspaceModifierNodeElement。

Bug 修复

  • 修复了 SubspaceModifier 排序以使其稳定。SubspaceModifier 应该表现得更可靠。偏移、旋转、缩放、可移动和可调整大小的修饰符现在应该可以按任意顺序使用。

版本 1.0.0-alpha01

2024 年 12 月 12 日

androidx.xr.compose:compose-*1.0.0-alpha01 已发布。

初始发布的功能

  • Jetpack Compose for XR 的初始开发者版本。使用熟悉的 Compose 概念（例如行和列）在 XR 中创建空间 UI 布局，无论你是将现有 2D 应用移植到 XR 还是从头开始创建新的 XR 应用。此库提供了子空间和空间可组合项：例如空间面板和轨道器，它们允许你将现有 2D Compose 或基于 Views 的 UI 放置在空间布局中。它引入了 Volume 子空间可组合项，允许你将 SceneCore 实体（例如 3D 模型）相对于你的 UI 进行放置。在此开发者指南中了解更多信息

    • Subspace：此可组合项可以放置在应用 UI 层次结构中的任何位置，让你可以在文件之间保持 2D 和空间 UI 的布局而不会丢失上下文。这使得在 XR 和其他外形设备之间共享现有应用架构等内容变得更容易，而无需通过整个 UI 树提升状态或重新架构你的应用。

    • SpatialPanel：空间面板是一种子空间可组合项，允许你显示应用内容——例如，你可以在空间面板中显示视频播放、静态图像或任何其他内容。

    • Orbiter：轨道器是一个空间 UI 组件。它旨在附加到相应的空间面板，并包含与该空间面板相关的导航和上下文操作项。例如，如果你创建了一个空间面板来显示视频内容，则可以在轨道器中添加视频播放控件。

    • Volume：将 SceneCore 实体（例如 3D 模型）相对于你的 UI 放置。

  • 空间布局：你可以创建多个空间面板，并使用 SpatialRow、SpatialColumn、SpatialBox 和 SpatialLayoutSpacer 将它们放置在空间布局中。使用 SubspaceModifier 自定义你的布局。

  • 空间 UI 组件：这些元素可以在你的 2D UI 中重复使用，并且它们的空间属性仅在启用空间功能时可见。

    • SpatialDialog：面板将在 Z 轴深度方向上稍微向后推，以显示一个抬高的对话框。
    • SpatialPopUp：面板将在 Z 轴深度方向上稍微向后推，以显示一个抬高的弹出窗口
    • SpatialElevation：可以设置 SpatialElevationLevel 以添加高程。

  • SpatialCapabilities：空间能力可以随着用户与你的应用或系统的交互而改变，甚至可以由你的应用本身改变——例如，进入 Home Space 或 Full Space。为了避免问题，你的应用需要检查 LocalSpatialCapabilities.current 来确定当前环境中支持哪些 API。isSpatialUiEnabled：空间 UI 元素（例如 SpatialPanel）isContent3dEnabled：3D 对象isAppEnvironmentEnabled：环境isPassthroughControlEnabled：应用程序是否可以控制透视状态isSpatialAudioEnabled：空间音频

已知问题

  • 目前使用 Jetpack Compose for XR 需要 minSDK 为 30。作为一种变通方法，你可以添加以下清单条目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便在 minSDK 为 23 的情况下构建和运行。
  • Jetpack XR 应用目前需要在 AndroidManifest 中请求 android.permission.SCENE_UNDERSTANDING 权限。
  • 当应用使用清单中的 PROPERTY_XR_ACTIVITY_START_MODE 属性直接启动到 Full Space 时，Activities/Applications 最初会在 Home Space 中打开，然后才转换到 Full Space。
  • Volume Composables 中的 glTFs 最初可能会在错误的位置闪烁。
  • 在已显著移动的面板中使用 SpatialDialog 会将内容推向错误的方向。