Jetpack Compose for XR

以声明方式构建可充分利用 Android XR 空间功能的空间界面布局。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2025 年 2 月 12 日 - - - 1.0.0-alpha02

声明依赖项

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

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

Groovy

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

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

Kotlin

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

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

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

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

创建新问题

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

1.0 版

版本 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 包含这些提交内容。

新功能

  • 现在，当启用空间对话框时，activity 面板可以遮罩其内容。
  • 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 方法，因此可以在非可组合上下文中使用它们。
  • 更新了空间高度级别，以符合最新的用户体验规范。
  • 将 SubspaceSemanticsInfo 接口实现到 MeasurableLayout。
  • 将 SubspaceModifierElement 重命名为了 SubspaceModifierNodeElement。

bug 修复

  • 修复了 SubspaceModifier 排序稳定性问题。SubspaceModifier 的行为应更加可靠。现在，偏移、旋转、缩放、可移动和可调整大小的修饰符应该可以按任何顺序使用。

版本 1.0.0-alpha01

2024 年 12 月 12 日

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

初始版本的功能

  • Jetpack Compose for XR 的初始开发者版本。无论您是将现有的 2D 应用移植到 XR，还是从头开始创建新的 XR 应用，都可以使用熟悉的 Compose 概念（例如行和列）在 XR 中创建空间界面布局。此库提供子空间和空间可组合项，例如空间面板和轨道器，可让您将现有的 2D Compose 或基于 View 的界面放置在空间布局中。它引入了 Volume 子空间可组合项，可让您相对于界面放置 SceneCore 实体（例如 3D 模型）。如需了解详情，请参阅此开发者指南：

    • Subspace：此可组合项可放置在应用界面层次结构中的任意位置，让您能够维护 2D 和空间界面的布局，而不会丢失文件之间的上下文。这样，您就可以更轻松地在 XR 设备和其他设备类型之间共享现有应用架构等内容，而无需在整个界面树中提取状态或重新构建应用。

    • SpatialPanel：SpatialPanel 是一种子空间可组合项，可让您显示应用内容，例如，您可以在 SpatialPanel 中显示视频播放、静态图片或任何其他内容。

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

    • 体积：相对于界面放置 SceneCore 实体（例如 3D 模型）。

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

  • 空间界面组件：这些元素可在 2D 界面中重复使用，并且只有在启用空间功能时，其空间属性才会显示。

    • SpatialDialog：面板将在 z 深度上稍微向后推，以显示提升式对话框。
    • SpatialPopUp：面板将在 z 深度上稍微向后推，以显示提升后的弹出式窗口
    • SpatialElevation：SpatialElevationLevel 可设置为添加海拔。

  • SpatialCapabilities：SpatialCapabilities 可能会随着用户与您的应用或系统互动而发生变化，甚至可能会由您的应用本身更改（例如，进入主屏幕或全屏模式）。为避免问题，您的应用需要检查 LocalSpatialCapabilities.current，以确定当前环境支持哪些 API。isSpatialUiEnabled：空间界面元素（例如 SpatialPanel） isContent3dEnabled：3D 对象 isAppEnvironmentEnabled：环境 isPassthroughControlEnabled：应用能否控制透传状态 isSpatialAudioEnabled：空间音频

已知问题

  • 目前，使用适用于 XR 的 Jetpack Compose 需要满足最低 SDK 版本为 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 属性直接启动到全局空间时，activity/应用会先在主屏幕空间中打开，然后再转换到全局空间。
  • 体积可组合项中的 glTF 最初可能会在错误的位置闪烁。
  • 在移动幅度较大的面板中使用 SpatialDialog 会将内容推向错误的方向。