向您的应用添加子空间

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

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

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

与任何其他可组合项一样，您可以直接在 2D UI 层次结构中调用 Subspace。但是，请务必注意在层次结构中调用 Subspace 的位置所产生的影响。

关于子空间层次结构

顶层子空间是您的应用调用的最外层子空间。将 ApplicationSubspace 可组合项用于您的顶层子空间，但是，如果您的应用中只使用 Subspace 可组合项，则最外层的 Subspace 可组合项将成为您的顶层子空间。默认情况下，此顶层子空间受观看应用的推荐空间限制，并且通常是您放置应用空间布局和 SpatialPanel 的位置。如果您需要更改顶层子空间的边界，请将不同的 VolumeConstraints 传递给您的 ApplicationSubspace。

然而，如果您在顶层子空间中包含的一个面板内的 2D UI 层次结构中嵌套了另一个子空间，则该嵌套子空间的行为会有所不同。

嵌套子空间与顶层 Subspace 有两个关键区别

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

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

  • 随父实体移动子实体
  • 使用偏移 SubspaceModifier 偏移子实体的位置
  • 呈现一个悬浮在 2D UI 上方并与 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