向应用添加子空间

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

您可以使用子空间可组合项（例如 Volume 和 SpatialPanel）来放置 3D 模型。某些 XR 组件（例如 Orbiter 或 SpatialDialog）是标准的 2D 可组合项，可在 2D 界面层次结构中的任何位置使用，但必须在应用的子空间中调用 SubspaceComposable。为此，请使用 ApplicationSubspace 可组合项或 Subspace 可组合项。

顾名思义，ApplicationSubspace 可组合项应包含应用的所有空间化内容。Subspace 可组合项非常适合在应用的现有界面层次结构中更深层次地嵌套 3D 空间的分区。

与任何其他可组合项一样，您可以在 2D 界面层次结构中直接调用 Subspace。不过，请务必了解在层次结构中的哪个位置调用 Subspace 会产生什么影响。

子空间层次结构简介

顶级子空间是应用调用的最外层子空间。请为顶级子空间使用 ApplicationSubspace 可组合项，但如果您在应用中仅使用子空间可组合项，则最外层 Subspace 可组合项将成为顶级子空间。默认情况下，此顶级子空间由查看应用的建议空间所限定，通常是放置应用的空间布局和 SpatialPanel 的位置。如果您需要更改顶级子空间的边界，请将不同的 VolumeConstraints 传递给 ApplicationSubspace。

不过，如果您在顶级子空间中包含的面板中嵌套另一个子空间，则该嵌套子空间的行为会有所不同。

嵌套子空间与顶级 Subspace 有两个主要区别：

  • 它们会参与调用它们的 2D 布局。这意味着子空间的高度和宽度将受其 2D 父布局的高度和宽度约束。
  • 它们的行为方式与它们在其中被调用的实体的子项相同。这意味着，如果您调用嵌套在 SpatialPanel 中的 Subspace 可组合项，则该子空间是其被调用的 SpatialPanel 的子项。

嵌套子空间的这些行为支持以下功能：

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

向应用添加子空间

以下代码示例展示了如何向应用添加顶级子空间和嵌套子空间：

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

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

@Composable
private fun PrimaryPane() {
    // This is a nested subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in a top-level Subspace
    Subspace {
        ObjectInAVolume(true)
    }
}
Subspace.kt