向应用添加子空间

适用的 XR 设备

本指南可帮助您为以下类型的 XR 设备打造优质体验。

了解 XR 设备类型 →

扩展现实头戴设备

有线扩展现实眼镜

了解 XR 设备类型 →

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

如需详细了解空间布局以及可在子空间中使用的组件，请参阅空间化组件。

子空间层次结构简介

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

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

PlanarEmbeddedSubspace 与 Subspace 有两个主要区别：

• 它们会参与调用它们的 2D 布局。这意味着，子空间的高度和宽度将受其 2D 父布局的高度和宽度限制。
• 它们充当调用它们的实体的子级。这意味着，如果您调用嵌套在 SpatialPanel 中的子空间可组合项，该子空间就是调用它的 SpatialPanel 的子级。

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

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

调整布局以适应子空间

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