Jetpack Compose for XR

Jetpack Compose for XR

用户指南  代码示例  Codelab

API 参考文档
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

以声明方式构建可利用 Android XR 空间功能的空间界面布局。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 7 月 30 日	-	-	-	1.0.0-alpha05

声明依赖项

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

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

Groovy

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

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

Kotlin

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

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

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

反馈

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

创建新问题

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

版本 1.0

版本 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 来支持未缩放的 GravityAligned 功能 (I07359)

API 变更

• SpatialDialog() 将遵循 SpatialDialogProperties.dismissOnBack 按压配置。（Ib453b、b/416797132）
• 将 minimumPanelDimension 更新为新的默认维度大小 Dimensions(0.1f, 0.1f, 0.1f)，因为其以米为单位表示。(Ib852a)
• 子空间和轨道飞行器现在会在主空间中以及应用处于后台时保留其内部状态。在居家空间模式下，Subspace 仍会设置其场景，以便为切换到完整空间模式做好准备。（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，用于接收插入符号的形状，以便提供更多自定义形状。（Ie513c、b/374766087、b/418854637）
• 移除了 CoreEntity 作为 PublishedApi 的身份 (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 中包含这些提交内容。

注意： 您需要使用 Android 模拟器 35.6.7 版或更高版本才能使用此版本的库。

新功能

• 添加了 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。当用户开始和结束移动可组合的子空间（使用 movable 修饰符）时，系统会调用 onMoveStart 和 onMoveEnd 回调。
• name 参数已从 SpatialRow 和 SpatialPanel 等空间 API 中移除。如需调试空间合成树，请改用 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 修饰符触发的重新布局阶段。
• 修复了当任一维度（直接或在布局计算期间，例如 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 中包含这些提交内容。

新功能

• 当空间对话框处于活动状态时，活动面板现在可以对其内容进行遮罩处理。
• Orbiter API 现在可在 SubspaceComposable 上下文中使用，并将 Orbiters 附加到其最近的基于 SubspaceLayout 的可组合父级。
• 引入了 LayoutCoordinatesAwareModifierNode 以允许自定义基于位置的修饰符。
• 向 SubspaceModifier.Node 添加了附加/分离生命周期方法。
• 向可移动修饰符添加了 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 或视图的界面放置在空间布局中。它介绍了 Volume 子空间可组合项，该可组合项允许您相对于界面放置 SceneCore 实体（例如 3D 模型）。如需了解详情，请参阅此开发者指南：

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

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

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

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

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

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

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

• SpatialCapabilities：空间功能可能会随着用户与应用或系统的互动而发生变化，甚至可以由应用本身更改，例如进入 Home Space 或 Full Space。为避免出现问题，您的应用需要检查 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"/>，以便能够使用 23 的 minSDK 进行构建和运行。
• Jetpack XR 应用目前需要在 AndroidManifest 中请求 android.permission.SCENE_UNDERSTANDING 权限。
• 当应用使用清单中的 PROPERTY_XR_ACTIVITY_START_MODE 属性直接启动到 Full Space 时，Activity/应用最初会在 Home Space 中打开，然后再过渡到 Full Space。
• Volume Composables 中的 glTF 最初可能会在错误的位置闪烁。
• 在已大幅移动的面板中使用 SpatialDialog 会将内容推向错误的方向。