Jetpack Compose for XR

声明依赖项

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

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

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"
}

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")
}

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

反馈

您的反馈将帮助我们改进 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，该 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)
• 返回处理功能现在适用于不包含嵌入 activity 的空间面板。如需返回处理功能正常运行，您需要在 Android 清单中指定 android:enableOnBackInvokedCallback="true"。
• 返回处理功能现在适用于空间对话框。为了使回调正常运行，您需要在 Android 清单中指定 android:enableOnBackInvokedCallback="true"。
• 基于 Compose 和基于 View 的 SpatialPanel 现在可以根据其内容调整大小。
• 现在，开发者可以设置自己的自定义 SpatialElevationLevel 值，而不局限于预定义的级别。
• 现在，您可以通过 elevation 参数自定义轨道器海拔级别。
• 默认情况下，子空间现在可以由 SpatialUser 的视野范围（宽度和高度）限定。如果无法确定视野范围，则使用默认的视野范围宽度和高度值。
• 向 Movable 修饰符添加了新的回调 onMoveStart 和 onMoveEnd。当用户开始和结束使用可移动修饰符移动子空间可组合项时，系统会调用 onMoveStart 和 onMoveEnd 回调。
• name 参数已从 SpatialRow 和 SpatialPanel 等空间 API 中移除。如需调试空间组合树，请改用 SubspaceModifier.testTag。
• 移除了仅包含 spatialElevationLevel 和 content 且不受支持的 SpatialPopup 重载。请使用支持 onDimissRequest 的接口。
• 移除了 Movable 修饰符中的 onPoseChange 回调。请改用 onMove。
• 如果这些 widget 已分离或正在分离，SubspaceModifiers 将不再应用其效果。
• 现有的 SpatialRow API 已拆分为 SpatialRow 和 SpatialCurvedRow。如果您之前使用的是 SpatialRow 的 curveRadius 参数，请改用 SpatialCurvedRow，它提供相同的行为。
• 在类似的近期系统映像上运行时，MainPanel 和 ActivityPanel 不再具有标题栏。
• Alpha 和缩放修饰符现在可堆叠，并且会对其值进行乘法运算，以得出最终应用的 Alpha 或缩放值。
• 优化了 Movable 修饰符中的 onPoseChange 回调，以实现更流畅的姿势移动。
• 可移动和可调整大小的修饰符现在将在主线程上执行回调，以确保状态更改会触发重组。
• 向布局和测量阶段添加了状态观察，以确保 SubspaceLayout 中的状态更改会触发重新布局。
• 优化了修饰符链更新，以更好地重复使用现有修饰符。

bug 修复

• 停止了在显示 SpatialDialog 时滚动。(Ic4594)
• 现在，在修饰符节点分离时发出的重新布局请求将被忽略。
• 移除了由 Movable 和 Resizable 修饰符触发的重新布局阶段。
• 修复了在直接或在布局计算（例如 SpatialRow/SpatialColumn 计算）期间将任一尺寸设置为零时，MainPanel() 可组合项发生崩溃的问题。现在，该面板将改为隐藏。请注意，此修复程序专门解决了布局阶段发生的崩溃问题；系统将单独处理通过用户互动将面板大小调整为零的情况。隐藏的面板缺少界面功能。
• 修复了可调整大小修饰符中的 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 包含这些提交内容。

新功能

• 现在，当启用空间对话框时，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 属性直接启动到 Full Space 时，activity/应用会先在 Home Space 中打开，然后再转换到 Full Space。
• 体积可组合项中的 glTF 最初可能会在错误的位置闪烁。
• 在移动幅度较大的面板中使用 SpatialDialog 会将内容推向错误的方向。