向应用添加子空间

适用的 XR 设备
本指南可帮助您为这些类型的 XR 设备打造体验。
了解 XR 设备类型 →
XR 头戴设备
有线 XR 眼镜
了解 XR 设备类型 →

子空间是应用中 3D 空间的一部分，您可以在其中放置 3D 模型、构建 3D 布局，以及为原本的 2D 内容添加深度。仅在启用空间化时，子空间才会呈现。在主空间或非 XR 设备上，该子空间内的任何代码都会被忽略。

您可以使用子空间可组合项（例如 SpatialPanel、SpatialRow 和 SpatialColumn）来创建布局并将 2D 内容放置在 3D 空间中。如需放置 3D 内容，请使用适当的子空间可组合项，例如 3D 模型的 SceneCoreEntity 和立体图片的 SpatialExternalSurface。某些 XR 组件（例如 Orbiter 或 SpatialDialog）是标准的 2D 可组合项，可在 2D 界面层次结构的任何位置使用，但 SubspaceComposable 必须在应用的子空间中调用。为此，请使用 Subspace 子空间可组合项。

子空间层次结构简介

顶级 Subspace 是由应用调用的最外层子空间。每次调用 Subspace 都会创建一个新的独立空间界面层次结构。它不会继承嵌套在其中的任何父级 Subspace 的空间位置、方向或缩放比例。

如需在 SpatialPanel、Orbiter、SpatialPopup 或其他组件中创建嵌入式或嵌套的 Subspace，请使用 PlanarEmbeddedSubspace。

PlanarEmbeddedSubspace 与 Subspace 之间存在两个主要区别：

  • 它们参与调用它们的 2D 布局。这意味着子空间的高度和宽度将受其 2D 父布局的高度和宽度的限制。
  • 它们表现为被调用实体的子实体。这意味着，如果您调用嵌套在 SpatialPanel 内的子空间可组合项，则该子空间是调用它的 SpatialPanel 的子空间。

PlanarEmbeddedSubspace 的这些行为可实现以下功能：

  • 将子实体与父实体一起移动
  • 使用偏移量 SubspaceModifier 偏移子布局的位置
  • 呈现悬浮在 2D 界面上方且高度和宽度与 2D 布局中相应空间相匹配的 3D 对象

为子空间调整布局

在 Android XR 上，默认情况下，应用的布局在全沉浸空间模式下会绑定到 Subspace 的 VolumeConstraints。因此，您应考虑用户可用的可见空间量，并相应地调整布局。recommendedContentBoxInFullSpace 为 ActivitySpace 内的边界框提供具体尺寸，以便将内容放置在用户的视野范围内。

应用的主要内容应位于此框内。如果您有内容必须超出建议的边界，请考虑采用鼓励用户通过移动头部来探索空间的布局。通过应用基于尺寸的自定义修饰符（例如 SubspaceModifier.requiredSizeIn），可以替换 recommendedContentBoxInFullSpace 的默认限制。对于无界行为，请设置 allowUnboundedSubspace = true。

使用当前 Session 调用 recommendedContentBoxInFullSpace，以根据需要获取这些特定维度。请参阅以下示例：

val session = LocalSession.current
session?.scene?.activitySpace?.recommendedContentBoxInFullSpace
Subspace.kt

为应用添加子空间

以下代码示例展示了如何向应用添加 Subspace 和 PlanarEmbeddedSubspace：

setContent {
    // This is a top-level subspace
    Subspace {
        SpatialPanel {
            MyComposable()
        }
    }
}
Subspace.kt

@Composable
private fun MyComposable() {
    Row {
        PrimaryPane()
        SecondaryPane()
    }
}

@Composable
private fun PrimaryPane() {
    // This is an embedded subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in the top-level Subspace
    PlanarEmbeddedSubspace {
        SpatialPanel {}
    }
}
Subspace.kt

如需了解详情，请参阅关于 Subspace 和 PlanarEmbeddedSubspace 的完整参考文档。