Jetpack Compose for XR

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

声明依赖项

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

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

Groovy

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

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

Kotlin

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

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

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

反馈

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

创建新问题

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

版本 1.0

版本 1.0.0-beta02

2026 年 10 月 21 日

发布了 androidx.xr.compose:compose:1.0.0-beta02 和 androidx.xr.compose:compose-testing:1.0.0-beta02。版本 1.0.0-beta02 包含这些提交内容。

API 变更

  • 库现在以 Kotlin 2.2 为目标平台，并且需要 kotlinc 2.2 (I82396, b/498369605)
  • 将 FollowMode.soft() 的 halfLifeMs 参数重命名为 halfLifeMillis。(I39187)
  • 将 PitchLimits 转换为 @JvmInline value class，将两个浮点数打包到一个 Long 中，以消除对象分配。(Id43c3)
  • 为 FollowMode.soft 添加了新参数：halfLifeMs、startDelay 和 startThresholds 参数。移除了参数 durationMs，因为在从 smoothStep 算法过渡到 exponentialDecay 算法后，不再需要该参数。(If0140)
  • 移除了已废弃的 SpatialActivityPanel 重载。请改用接受 SpatialActivityPanelController 的 SpatialActivityPanel 重载。(I5abc3)
  • 在 FullSpaceMode 中，支持在单个 Activity 内实现 3D 和 2D 可组合项内容之间的转换。此变更受 SpatialComposeFlags.isMainPanelResetOnSubspaceDisposeEnabled 控制。(I4e237)
  • 公开了接受 FollowTarget 参数的实验性 Subspace 过载，以支持以下内容。(Iec1a9)
  • 移除了已废弃的可移动修饰符。请改用新的可移动修饰符，该修饰符接受新的 MovePolicy 作为参数。(Ib135d)
  • 移除了已废弃的 DragPolicy。已改用 SubspaceModifier.movable()。(I108d4)
  • 废弃了无状态 Slider 和 RangeSlider 重载，改为使用其有状态版本。将 RangeSliderState 中的 activeRangeStart 和 activeRangeEnd 重命名为了 startValue 和 endValue，并弃用了带有 DeprecationLevel.HIDDEN 的旧版未升级和实验性 Slider API。(If8995)

bug 修复

  • 通过引入 poseInActivitySpace 修复了 RotateToLookAtUser，以确保为所有子空间类型（包括附加到锚点或用户的子空间类型）正确计算姿势。Ica367b
  • 修复了 Orbiter 附加到大型面板时发生的 Constraints 崩溃问题 (I8c4bf)
  • 修复了 SubspaceLayoutNode 中的一个 bug，即 removeAll() 会导致不必要的 ArrayList 分配。还修复了深度计算性能问题。I34a10a
  • androidx.lifecycle:lifecycle-runtime 依赖项已更新至 2.10.0。此版本是捆绑的生命周期运行时 lint 检查在 AGP 9.5.0-alpha04 或更高版本中运行所必需的。（I99bfd、b/556807521）
  • 改进了与 AudioOutputProvider 相关的 kdoc，以强调不应将其与多个 ExoPlayer 实例重复使用 (I6b18e)
  • 修复了 kdoc 的一些细微拼写和语法问题 (Id3ba6)

已知问题

  • 此版本的 androidx.xr.compose 依赖于 androidx.xr.scenecore:1.0.0-rc01，后者存在已知的内存泄漏问题。在 build 配置中，您可以明确将 SceneCore 依赖项替换为 1.0.0 版本，其中包含针对内存泄漏问题的修复。

版本 1.0.0-beta01

2026 年 9 月 23 日

发布了 androidx.xr.compose:compose:1.0.0-beta01 和 androidx.xr.compose:compose-testing:1.0.0-beta01。版本 1.0.0-beta01 包含这些提交内容。

API 变更

  • 移除了已废弃的 DragPolicy。已改用 SubspaceModifier.movable()。(I108d4)
  • 移除了已废弃的 ResizePolicy 及其在 SpatialPanel 和 SpatialExternalSurface 中的用法。移除了已废弃的 SubspaceModifier.resizable 函数。请改用新的 SubspaceModifier.resizable 和新的 ResizePolicy。(I59e6b)
  • 添加了 isPitchUpdateEnabled 参数，以便单独启用或停用音高跟踪。(Ie9e86)
  • 移除了 pitchLimits 的可为 null 性，并将 PitchLimits.UNCONSTRAINED 重命名为 PitchLimits.FullRange。(I0154f)
  • ExposedDropdownMenu 现在是 ExposedDropdownMenuBoxScope 的扩展函数，而不是成员。您可能需要使用新的导入语句来更新代码。(Ie8a65)
  • 移除了已废弃的 SurfaceProtection 类。已改用 SpatialExternalSurfaceProtection。(Iab2c6)
  • 采用 OrbiterPoseProvider 的 Orbiter 函数已被弃用，取而代之的是使用 SpatialAlignment 的函数。(I4d12b)
  • SpatialActivityPanel 现在需要 SpatialActivityPanelController（使用 rememberSpatialActivityPanelController 实例化）来启动和管理嵌入式 activity。(Id25c6)
  • 从 rotateToLookAtUser 中移除了 upDirection 参数，并添加了旋转限制参数（isYawUpdateEnabled 和 pitchLimits）。(I1370a)

bug 修复

  • 修复了各种 InteractionPolicy 问题。如果输入事件发生在可组合项或子项（例如 Orbiter）启动处置序列时，则会发生崩溃。还修复了子级会收到悬停事件的问题。(Ifc477)
  • 缩小了 RotateToLookAtUserActivity 中的面板尺寸，以防止在视野较小的设备上出现画面被裁剪的情况。(I8d672)

已知问题

  • Compose XR 面板存在一个问题：在单个 activity 中创建多个面板可能会导致正在查看的内容出现一些损坏，即使在面板销毁后也是如此。

版本 1.0.0-alpha17

2026 年 8 月 12 日

发布了 androidx.xr.compose:compose:1.0.0-alpha17 和 androidx.xr.compose:compose-testing:1.0.0-alpha17。版本 1.0.0-alpha17 包含这些提交内容。

API 变更

  • 移除了 Meter 值类，该类在 Scenecore 中被 virtualPixelDensity 替换。(I690ee)
  • SpatialGltfModel API 目前处于实验阶段，必须选择启用才能使用。(I4557e)
  • 将 system resizable 设为可为 null (Ib0093)
  • 在 SubspaceSemanticsInfo 中公开了 Density，用于测试。(I2e826)
  • 将 ResizePolicy 默认选项重命名为 system，并添加了不带参数的新 Default 选项 (Ic8b16)
  • 将 FollowTarget 标记为实验性。整个 FollowingSubspace API 目前处于实验阶段。(Id4ee3)
  • 移除了 GltfAnimation API (Ic2894)
  • 将参数化 MovePolicy.default() 方法重命名为 MovePolicy.system()。引入了 val MovePolicy.Default 属性，用于表示标准默认移动行为。(Iedcc9)
  • 将 ExperimentalMoveAnchorPolicy 选择启用要求扩展到 PlaneSemantic 和 PlaneOrientation (Ief927)
  • 从 VolumeConstraints.offset 中移除了 resetMins (Ib2f2f)
  • 移除了已弃用的 SceneCoreEntitySizeAdapter 函数。(Ib6722)
  • 移除了已废弃的 Subspace 重载，并替换为 allowUnboundedSubspace。(I8e97f)
  • 移除了已废弃的语义修饰符重载。(I4ac10)

bug 修复

  • 修复了以下问题：附加了 InteractionPolicy 的 Composable 的子级会触发输入事件 (Icdba6)

版本 1.0.0-alpha16

2026 年 7 月 15 日

发布了 androidx.xr.compose:compose:1.0.0-alpha16 和 androidx.xr.compose:compose-testing:1.0.0-alpha16。版本 1.0.0-alpha16 包含这些提交内容。

API 变更

  • 移除了 ComponentOverride API (I820c4)
  • GltfAnimation 和 SpatialGltfModelAnimation API 已标记为实验性。某些属性已转换为 getter。（I8d689、b/524771027）
  • 通过将米和像素之间的转换设置为常量，修复了整体密度行为。Meter.kt 已废弃，现在可以使用 Session.scene.virtualPixelDensity 作为替代方案。（I122ff、b/430097855、b/474168798）
  • 更新了 resizable 修饰符，以使用一个 ResizePolicy，而不是两个修饰符 (I7fb0f, b/496257436, b/519672992)
  • 向 SubspaceAssertions.kt 中的所有公共浮点维度和位置相等性断言添加了 tolerance: Dp = Dp(0.5f) 参数。默认容忍度行为 (0.5.dp) 已完整记录。（I266cb、b/521491915）
  • 添加了带有 movePolicy 参数的可移动重载，并废弃了 transformingMovable 和 movable (Ic88c1, b/481781189)
  • 添加了遵循 Material Expressive 规范的标准列表项和分段列表项的新非交互式变体。非表达版本已被弃用。（Ide4de、b/491994186）
  • 对于子空间，allowUnboundedSubspace 参数现已弃用并隐藏。现在，应通过在 Subspace 修饰符上使用 SubspaceModifier.requiredSizeIn(maxWidth = Dp.Infinity, maxHeight = Dp.Infinity, maxDepth = Dp.Infinity) 来实现无边界行为。allowUnboundedSubspace 参数已从 FollowingSubspace 中移除。（Ia72ae、b/433624021）
  • 将 Session.create 转换为挂起函数。(I5d27f)
  • 添加了 SubspaceModifier.spatializedAudioOutput，允许通过 ExoPlayer 或 SoundEffectPlayer 空间化音频播放（I46697、b/489421980、b/497867019）
  • 更新了 ComponentActivity.requestHomeSpace() 和 requestFullSpace()，以返回 SpaceRequestResult 进行状态验证。(If1672)
  • 将 AnchorEntity 更新为 AnchorSpace (Ifa95e, b/513619219)
  • 取消了对 SpatialGltfModelSource 中 fromResource 方法的限制 (I1f5a1, b/503047416)
  • SubspaceSemanticsMatcher 成员是公开的：description 属性、伴生工厂方法（expectValue、keyIsDefined、keyNotDefined）、成员函数（matches、matchesAny）和运算符（and、or、not）。(I972a4, b/460427288)
  • 更新了 SubspaceModifier.semantics、SubspaceModifier.testTag、SubspaceSemanticsInfo、SubspaceSemanticsModifierNode，以使用精选的空间语义类型。（I80dea、b/460427288）
  • 在 SpatialAlignment 中将 position 重命名为 align，并移除了各个方向偏移方法，改为使用统一的 align API。（I9bdb2、b/479805937）
  • 从 SpatialConfiguration 中移除了已废弃的 Space Mode API。（I1ef5c、b/458712461）
  • 推出了 SubspaceSemanticsConfiguration。这是空间节点的语义属性配置。此类可安全地公开 3D 语义的查询方法，而不会向外部使用者泄露基础 2D 语义功能。（Id025e、b/460427288）
  • 引入了 SubspaceSemanticsPropertyReceiver：一个专用封装容器，可将 3D 布局容器属性限制为有效字段（最初为 testTag 和 contentDescription）。(I5cf5c, b/460427288)

bug 修复

  • 将语义修饰符的 hasContentDescription 更新为默认使用子字符串匹配。(I08214)
  • 添加了受限的 FollowBehavior.ExponentialDecay()，它提供由弹性物理学引导的软跟随行为。（I7449c、b/485639909、b/500493335）

大多数 API 都会受到影响。具体而言，LocalSession CompositionLocal 和依赖于 LocalSession 的所有 CompositionLocals（例如 LocalSpatialConfiguration、LocalSpatialCapabilities 等）现在都会在 Session 初始化之前解析为 null 或其非 XR 版本。

Session 可用后，系统会以正确的状态触发重组。（I0cfa4、b/514712835、b/514712835）

  • 阐明了 ComponentActivity.requestHomeSpace 和 ComponentActivity.requestFullSpace 的文档，涉及挂起行为、取消和并发。更新了测试，以验证 CancellationException 传播。（I22f75、b/493289528）

版本 1.0.0-alpha15

2026 年 6 月 17 日

发布了 androidx.xr.compose:compose:1.0.0-alpha15 和 androidx.xr.compose:compose-testing:1.0.0-alpha15。版本 1.0.0-alpha15 包含这些提交内容。

API 变更

  • 废弃了 ResizePolicy 和旧的可调整大小修饰符，取而代之的是新的 SubspaceModifier.resizable 重载和 SubspaceModifier.transformingResizable。(I9e4bc)
  • 更新了 SpatialGltfModel API：添加了对通过 SpatialGltfModelSource.fromResource 从资源加载模型的支持。在 SpatialGltfModelAnimation 中将 speed 重命名为 playbackSpeed，并添加了 resume() 方法。SpatialGltfModelStatus.Loaded 和 Loading 现在是对象。(I523de)
  • 将 rotateToLookAtUser 标记为实验性 API。(I86c16)
  • 将受保护的变量 targetCurrentPose 移至局部变量 currentTargetPoseMeter 并重命名。(Ia557c)
  • 更新了 SpatialPanel 和 SpatialExternalSurface kdoc，以包含对象在其布局大小中的呈现位置 (I72104)
  • 在 SpatialGltfModelState 中封装了 SpatialGltfModel 加载逻辑，并阐明了失败行为。(Ibe98b)
  • 在 SubspaceModifer.size kdocs 中阐明了 depth (I0f84f)

版本 1.0.0-alpha14

2026 年 5 月 19 日

发布了 androidx.xr.compose:compose:1.0.0-alpha14 和 androidx.xr.compose:compose-testing:1.0.0-alpha14。版本 1.0.0-alpha14 包含这些提交内容。

API 变更

  • 引入了 transformingMovable，用于默认由系统处理的 3D 移动；并引入了 movable 的新重载，用于处理自定义移动行为。(I50960)
  • 已移除SpatialGltfModel.fromData()。(I4d083)
  • 添加了新的修饰符节点接口 SubspaceMeasuredSizeAwareModifierNode，该接口在测量传递后提供 onRemeasured 回调。SubspaceLayoutAwareModifierNode 现在扩展了此新接口。onSizeChanged 修饰符已更新为使用 onRemeasured，以确保在测量后立即触发回调，而不是在放置后触发。(Iafbae)
  • 将 InteractionPolicy 更新为 Interface (I0ff30)
  • 将 Compose compileSdk 更新到了 API 37。这意味着，使用 Compose 时，AGP 版本至少需要为 9.2.0。(Id45cd)
  • 更新了 Size kdocs (Iefa9a)

版本 1.0.0-alpha13

2026 年 5 月 6 日

发布了 androidx.xr.compose:compose:1.0.0-alpha13 和 androidx.xr.compose:compose-testing:1.0.0-alpha13。版本 1.0.0-alpha13 包含这些提交内容。

API 变更

  • Orbiter API 还有待进一步更改，我们建议您忽略 Orbiter 的弃用通知，并留意即将发布的版本中 Orbiter 的更改。
  • 使用 SceneCoreEntity 呈现 glTF 的用户应确保将 session.scene.activitySpace 传递给其 GltfModel.create 调用的 parent 参数，以确保其 glTF 能够呈现。
  • 添加了 SpatialGltfModel API，以便开发者向其 Compose for XR 应用添加 Gltf。开发者还可以查询其 glTF 模型中的动画和节点。（I8b542、b/495422586）
  • 将 SceneCoreEntitySizeAdapter 从类更改为接口 (I5a784, b/475292310)
  • SurfaceProtection 已重命名为 SpatialExternalSurfaceProtection。更新了 SpatialExternalSurface kdocs (Ifad0a, b/485231082)
  • 弃用 currentWindowAdaptiveInfo 并引入其 V2 版本 (I40ecf, b/424442112)
  • resizable 修饰符现已公开，并适用于组（例如 SpatialRow）。(I2bcf6, b/348483527, b/489753178, b/479530787)
  • movable 修饰符现已公开。目前，此修饰符适用于 SpatialPanels 和 SpatialExternalSurface；不过，我们的目标是让所有 SubspaceComposables 都能很好地支持此修饰符。（I9a3cd、b/479530787、b/478935063、b/478935063）
  • SpatialEnterTransition 和 SpatialExitTransition 已标记为 @Immutable (If1710, b/487757837)
  • SpatialGltfModel API 在此版本中被标记为受限，有待进一步测试。（Ibf003、b/466090694）
  • 将 DeviceTrackingMode.LAST_KNOWN 重命名为 SPATIAL_LAST_KNOWN（具有已弃用的回退），为 3DoF 跟踪添加了 INERTIAL_LAST_KNOWN，并向 TrackingState 添加了 TRACKING_DEGRADED。（Ie661c、b/445466590）
  • 移除了已废弃的 SpatialLayoutSpacer (I7b36c)
  • 移除了已废弃的 padding API (If1886)
  • 添加了 floatRange 以偏置值。移除了 LayoutDirection 的默认值 (I9d74e)

bug 修复

  • 为 SpatialColumn、SpatialRow 和 SpatialCurvedRow 添加了代码示例和 KDoc 文档。（Iaf54f、b/495777633）

版本 1.0.0-alpha12

2026 年 3 月 25 日

发布了 androidx.xr.compose:compose:1.0.0-alpha12 和 androidx.xr.compose:compose-testing:1.0.0-alpha12。版本 1.0.0-alpha12 包含这些提交内容。

API 变更

  • 添加 SpatialGltfModel API 和 SpatialGltfModelAnimation API，以渲染 glTF 并控制动画。SpatialGltfModelState 已更改为 AutoCloseable，现在需要将其关闭以释放其资源。（I11fde、b/466065486、b/481379924）。不过，SpatialGltfModel API 在此版本中被标记为受限，有待进一步测试。（Ibf003、b/466090694）
  • 为 SubspaceModifier.rotate 添加了已弃用的空重载。(Idceb6)
  • 将 SpatialSmoothFeatheringEffect 函数重命名为 spatialSmoothFeatheringEffect，并将其移至 draw 模块。将 SpatialExternalSurface 默认羽化值更新为 null，这会模拟旧的 ZeroFeatheringEffect 功能。（I5fdaa、b/460426800）
  • 移除了 onPointSourceParamsAvailable。我们将在不久的将来提供其他音频空间化 API。（I86507、b/458513439）
  • 为偏移子空间修饰符添加了 RTL 行为。还添加了 absoluteOffset 以忽略布局方向。（I30e4b、b/474409165）

版本 1.0.0-alpha11

2026 年 2 月 25 日

发布了 androidx.xr.compose:compose:1.0.0-alpha11 和 androidx.xr.compose:compose-testing:1.0.0-alpha11。版本 1.0.0-alpha11 包含这些提交内容。

新功能

  • 向 SpatialExternalSurfaces 添加了 SuperSampling 参数 (Icd4d1)

已知问题

  • SceneCore 中的 SurfaceEntity 存在问题，可能会导致应用在创建 SpatialExternalSurface 实例时崩溃。此问题已在 androidx.xr.scenecore:scenecore-*:1.0.0-alpha13、androidx.xr.compose:compose:1.0.0-alpha12 及其后续版本中得到解决。受影响的应用应更新到最新版本。

API 变更

  • 子空间修饰符内边距更改，以感知布局方向。(I53e25)
  • SpatialCapabilities 现已封存，无法延期。(I07aef)
  • 接受通用 SpatialAlignment 参数的 SpatialRow 和 SpatialColumn API 已废弃；请改为使用分别接受 verticalAlignment 或 horizontalAlignment 的 SpatialRow 和 SpatialColumn API。(Iec390)
  • 合并了重载 SubspaceLayout 函数 API (Idd30a)
  • 将 SubspaceModifier.lookAtUser 重命名为 rotateToLookAtUser，并将 up 参数重命名为 upDirection。(Icafb8)
  • 将 SpatialRow 设为内联函数 (Ia2f20)
  • 使 SpatialColumn 成为内联函数 (I681be)
  • 移除了 billboard API (Ib76cd)

版本 1.0.0-alpha10

2026 年 1 月 28 日

发布了 androidx.xr.compose:compose:1.0.0-alpha10 和 androidx.xr.compose:compose-testing:1.0.0-alpha10。版本 1.0.0-alpha10 包含这些提交内容。

API 变更

版本 1.0.0-alpha09

2025 年 12 月 3 日

发布了 androidx.xr.compose:compose:1.0.0-alpha09 和 androidx.xr.compose:compose-testing:1.0.0-alpha09。版本 1.0.0-alpha09 包含这些提交内容。

API 变更

  • 添加 LookAtUser 和 Billboard 修饰符，使内容始终面向用户。(I49b99)
  • 添加了将 InteractionPolicy 设置为 SpatialExternalSurfaces 和 SpatialPanels 的功能，从而可以检测点击和其他 3D 输入事件。(Iae155)
  • 添加了 size 和 requiredSize 修饰符重载，其中宽度、高度和深度为 Dp 值。(I92f79)
  • ParentLayoutParamsModifier 接口现在扩展了 DelegatableSubspaceNode。(I1a6d4)
  • ApplicationSubspace 已弃用，取而代之的是 Subspace API。
    • Subspace API 行为已更改为仅在推荐的姿势和比例下提供应用范围的子空间。
    • 引入了 PlanarEmbeddedSubspace API，以便在 2D 上下文中提供嵌入式子空间。(Id3343)
  • 向 SubspaceModifier.Node API 添加了 shouldAutoInvalidate 标志。(I93902)
  • 添加了 required(Size|Width|Depth|Height)In API，可让开发者将 @SubspaceComposable 的大小限制在特定范围内，而无需考虑父级的传入测量约束条件。(Ifaa78)
  • 添加了 SubspaceModifier.onSizeChanged，可提供简单、集中的回调，以便开发者在 @SubspaceComposable 的大小发生变化时做出响应。(I994f9)
  • 移除了 Volume API。应使用 SceneCoreEntity API，而不是 Volume API。(I4162b)
  • 将 SubspaceLayoutModifierNode.requestRelayout 拆分为 invalidateMeasurement/invalidatePlacement。(I14805)
  • 添加了 SpatialGltfModel API，可让开发者在 Compose 中渲染 glTF。(Icc91f)
  • 引入了 SpatialGltfModel 可组合 API，以便轻松渲染 glTF (Iade67)

bug 修复

  • 修复了 SceneCoreEntity 中的布局 bug。现在，它应该会正确遵循其约束条件。(I11bb8)
  • 将 jxr-compose 模块降至 Compile sdk = 34 (I2d5db)

版本 1.0.0-alpha08

October 22, 2025

发布了 androidx.xr.compose:compose:1.0.0-alpha08 和 androidx.xr.compose:compose-testing:1.0.0-alpha08。版本 1.0.0-alpha08 包含这些提交内容。

API 变更

  • 将 ResizePolicy 更改为接受 onResizeStart、onResizeUpdate 和 onResizeEnd。(I7e21f)

bug 修复

  • 防止在销毁具有 Subspace 的 Activity 时发生崩溃。(I595a1)

版本 1.0.0-alpha07

2025 年 9 月 24 日

发布了 androidx.xr.compose:compose:1.0.0-alpha07 和 androidx.xr.compose:compose-testing:1.0.0-alpha07。版本 1.0.0-alpha07 包含这些提交内容。

API 变更

  • 改进了 SpatialMainPanel 的 KDoc。（I27b70、b/444467891）
  • 引入了 SpatialArrangement，用于在 SpatialRow 和 SpatialColumn 等 3D 布局中沿主轴排列子项。这个新 API 提供了 2D Compose 中熟悉的排列选项，包括 Start、End、Center、SpaceBetween、SpaceAround 和 SpaceEvenly，并全面支持 LTR 和 RTL 布局方向。（I7db38、b/436289959）
  • 为 SubspaceModifier.Node 添加了基本接口，以提高扩展接口的类型安全性和易用性；例如
    • CompositionLocalConsumerSubspaceModifierNode
    • LayoutCoordinatesAwareModifierNode
    • SubspaceLayoutModifierNode
    • CoreEntityNode（内部）(Iede00, b/440599394, b/440599394)
  • 取消了对 SpatialExternalSurface 的限制 (I33315, b/439646773)
  • 向 Subspace 可组合项引入了 SubspaceModifier，并将 constraints 参数替换为 SubspaceModifier 和与大小相关的 SubspaceModifiers。如果 allowUnboundedSubspace 为 true，则子空间仍可以具有无界限约束条件。（Ib06e6、b/433331675）
  • 由于 DragPolicy() 和 ResizePolicy() 现已成为 SpatialPanel 和 SpatialExternalSurface API 的一部分，因此弃用可移动和可调整大小的 SubspaceModifiers (I397bf, b/437924639)
  • 在空间布局中添加了对 LayoutDirection 的支持。现在，使用 SpatialAlignment 的可组合项会在 LTR 和 RTL 上下文中正确放置元素。（I964bb、b/436300273）
  • 向 Panel API 添加 Resizable 和 Movable 参数，以确保这些行为只能应用于受支持的容器。(Id491c)
  • 添加了 sizeIn、widthIn、heightIn、depthIn SubspaceModifiers，可让您为宽度、高度和深度设置确切的最小和最大约束条件。（I1af09、b/433330761）

版本 1.0.0-alpha06

2025 年 8 月 13 日

发布了 androidx.xr.compose:compose:1.0.0-alpha06 和 androidx.xr.compose:compose-testing:1.0.0-alpha06。版本 1.0.0-alpha06 包含这些提交内容。

bug 修复

  • 在生命周期所有者被销毁时重新创建 ComposeXrOwnerLocals。(9123ce1)

版本 1.0.0-alpha05

2025 年 7 月 30 日

发布了 androidx.xr.compose:compose:1.0.0-alpha05 和 androidx.xr.compose:compose-testing:1.0.0-alpha05。版本 1.0.0-alpha05 包含这些提交内容。

新功能

  • 将 SubspaceComposable 注解类设为公开。（Ic2a34、b/399432430）
  • 新增了两个 SpatialExternalSurface 可组合项，分别表示 180 度和 360 度球体。（I40ef2、b/391705799）
  • 添加了 SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147)
  • 添加了 SceneCoreEntity API，以提高 SceneCore 与 Compose for XR 之间的互操作性。（I50bb3、b/423020989）
  • 提供了 GravityAlignedsubspace API，以支持未缩放的 And GravityAligned 功能 (I07359)

API 变更

  • SpatialDialog()将遵循SpatialDialogProperties.dismissOnBack按压配置。（Ib453b、b/416797132）
  • 将 minimumPanelDimension 更新为新的默认尺寸 Dimensions(0.1f, 0.1f, 0.1f)，因为其单位为米。(Ib852a)
  • 现在，子空间和 Orbiter 在主共享空间中以及应用在后台运行时，都会保留其内部状态。在主共享空间模式下，子空间仍会设置其场景，为切换到全沉浸空间模式做好准备。（I40317、b/416037751）
  • 现在，当应用在后台运行时，SpatialDialogs 会保留其状态。(I6aa56)
  • ApplicationSubspace 现在将从系统继承其推荐的缩放比例和位置。（I4565f、b/418834194）
  • 添加了更明确的出错提示，并在非 SubspaceComposable 上下文中使用 SubspaceComposable 时更早地触发错误。（Iee2ae、b/416484684）
  • 将 ExperimentalSubspaceVolumeApi 从“警告”更新为“错误”，因为在误用可组合 API 时，警告通常会被忽略。（I427aa、b/424864286）
  • 子空间和 ApplicationSubspace 现在受 recommendedContentBoxInFullSpace 约束。之前，它受 SpatialUser 的视野范围限制。（I41015、b/423074142）
  • 更新了 SpatialElevation，使其使用最小尺寸，不再使用硬编码尺寸（I2dbe6、b/427785338）
  • 更新了在修改关键变量时如何对 SpatialAcitivityPanel 进行遮罩。（I0f64d、b/427999029）
  • 移除 VolumeConstraints.Unbounded，改为将默认限制条件值设置为等效值。（Ie24ec、b/407938414）
  • SpatialFeatheringSize 不再公开（I1c15b、b/399432430）
  • 将 XR Placeable 重命名为 SubspacePlaceable，以便与 Compose 的 Placeable 区分开来。(I74874)
  • 移除 Orbiter 设置，并添加 shouldRenderInNonSpatial 作为新参数。此外，移除 EdgeOffset 类并添加 orbiterOffsetType 作为新参数，以整合 Orbiter() 函数。以及将 OrbiterEdge 重命名为 ContentEdge。(Iebf3d)
  • 已将 Measurable 重命名为 SubspaceMeasurable，以便将该类型与 Compose 的 Measurable 类型区分开来。(I9726c)
  • 将 MeasureResult 重命名为 SubspaceMeasureResult (I9f34d)
  • 移除了 setSubspaceContent API，改为将 Compose 的 setContent 与 Subspace 可组合项搭配使用。（Ifff4c、b/421427391、b/421427391）
  • 将 MeasurePolicy 重命名为 SubspaceMeasurePolicy。（I37a9b、b/422553904）
  • 将 SubspaceSemanticsInfo 转换为密封接口，因为如果没有默认值，我们将无法添加成员。（I372f9、b/423704068）
  • 更新了 SpatialExternalSurface 文档，并将 ContentSecurityLevel 重命名为 SurfaceProtection (I3c460, b/420982808)
  • 为可移动修饰符提供了重载构造函数，该修饰符允许锚定。(Ic0c70)
  • 为提示添加了更多位置提供程序，现在开发者可以控制提示是放置在锚点的上方、下方、左侧还是右侧。添加了一个 API，该 API 接受 Shape 作为光标，以便提供更多自定义形状。（Ie513c、b/374766087、b/418854637）
  • 移除了作为 PublishedApi 的 CoreEntity (Ifee05)

bug 修复

  • 修复了 SpatialDialog 在渲染时会闪烁的问题。（Ife73c、b/401619909）
  • 修复了 SpatialDialog 无法遮盖 activity 面板的问题。（I8ca6c、 b/367442109）
  • 修复了 XR 对话框不显示某些内容的问题 (I17cd5, b/418062437)
  • 修复了点击内容内部时 SpatialPopup 会关闭的问题。（If262c、b/417245722）
  • 修复了以下问题：在链接 resizable().movable() 时，SpatialPanel 无法正确调整为新大小。（I02ee3、b/422264230）
  • 修复了 SpatialComposeVideoPlayer 中 topBar 与菜单重叠的问题 (Id33bc, b/427168167)
  • 修复了圆角半径无法渲染的问题 (I975fe, b/428261830)

版本 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 类型访问组合本地值。
  • 添加了遵循 Compose AndroidView 实现样式的新 SpatialPanel API，并废弃了之前的 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。当用户开始和结束移动具有 movable 修饰符的子空间可组合项时，系统会调用 onMoveStart 和 onMoveEnd 回调。
  • name 参数已从 SpatialRow 和 SpatialPanel 等空间 API 中移除。如需调试空间 Compose 树，请改用 SubspaceModifier.testTag。
  • 移除了仅具有 spatialElevationLevel 和 content 的不受支持的 SpatialPopup 重载。请使用支持 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 计算）期间将任一维度设置为零时发生。现在，该面板将被隐藏。请注意，此修复专门针对布局阶段的崩溃问题；通过用户互动将面板大小调整为零的情况将单独处理。隐藏的面板缺少界面功能。
  • 修复了 resizable 修饰符中的 maintainAspectRatio 问题。现在应保持宽高比。
  • 修复了嵌套 Subspace 在单帧中位置不正确的问题。
  • 修复了有时未在应应用圆角时应用圆角的问题。
  • 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 包含这些提交内容。

新功能

  • 现在，当空间对话框处于启用状态时，活动面板可以遮盖其内容。
  • 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 方法，因此可以在不可组合的上下文中使用。
  • 更新了空间高度级别，以符合最新的用户体验规范。
  • 在 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 的初始开发者版本。无论您是要将现有 2D 应用移植到 XR，还是要从头开始创建新的 XR 应用，都可以使用熟悉的 Compose 概念（例如行和列）在 XR 中创建空间界面布局。此库提供子空间和空间可组合项，例如空间面板和轨道器，可让您将现有的 2D Compose 或基于 View 的界面放置在空间布局中。它引入了 Volume 子空间可组合项，可让您相对于界面放置 SceneCore 实体（例如 3D 模型）。如需了解详情，请参阅此开发者指南：

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

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

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

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

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

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

    • SpatialDialog：面板会在 Z 轴深度上略微后退，以显示浮起的对话框。
    • SpatialPopUp：面板将在 Z 轴深度上略微向后推，以显示浮起的弹出式窗口
    • SpatialElevation：可设置 SpatialElevationLevel 以增加高度。

  • SpatialCapabilities：空间功能可能会随着用户与应用或系统的互动而发生变化，甚至可能由应用本身进行更改，例如进入主共享空间或全沉浸空间。为避免出现问题，您的应用需要检查 LocalSpatialCapabilities.current，以确定当前环境支持哪些 API。 isSpatialUiEnabled：空间界面元素（例如 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 属性直接启动到全沉浸空间时，Activity/应用最初会在主共享空间中打开，然后再过渡到全沉浸空间。
  • Volume 可组合项中的 glTF 最初可能会在错误的位置闪烁。
  • 在已大幅移动的面板中使用 SpatialDialog 会将内容推向错误的方向。