向应用添加子空间

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
扩展现实头戴设备
有线扩展现实眼镜
了解 XR 设备类型 →

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

您可以使用子空间可组合项（例如 SpatialPanel、SpatialRow、 和 SpatialColumn）来创建布局，并在 3D 空间中放置 2D 内容。如需放置 3D 内容，请使用适当的子空间可组合项，例如 SceneCoreEntity用于 3D 模型的 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 上，默认情况下，应用的布局会绑定到 VolumeConstraints 的 Subspace。因此，您应考虑用户可用的可见空间量，并相应地调整布局。recommendedContentBoxInFullSpace 为 ActivitySpace 内的边界框提供了 具体尺寸，以便将内容放置在用户的视野范围内。

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

使用当前 会话 调用 recommendedContentBoxInFullSpace，以 根据需要获取这些具体尺寸。请参阅以下示例：

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

向应用添加子空间

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

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

@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 和 PlanarEmbeddedSubspace 的完整参考文档。