在應用程式中新增子區

子空間是應用程式內 3D 空間的分區，可在其中放置 3D 模型、建構 3D 版面配置，以及為其他 2D 內容加上深度。只有在啟用空間化功能時，系統才會算繪子空間。在 Home Space 或非 XR 裝置上，系統會忽略該子空間中的任何程式碼。

您可以使用子區域可組合函式 (例如 Volume 和 SpatialPanel) 來放置 3D 模型。部分 XR 元件 (例如 Orbiter 或 SpatialDialog) 是標準的 2D 可組合函式，可用於 2D UI 階層中的任何位置，但 SubspaceComposable 必須在應用程式的子區域中叫用。如要執行這項操作，請使用 ApplicationSubspace 可組合函式或 Subspace 可組合函式。

如名稱所示，ApplicationSubspace 可組合函式應包含應用程式的所有空間化內容。Subspace 可組合項非常適合在應用程式現有的 UI 階層中，將 3D 空間的分區巢狀結構更深入。

如同其他可組合項，您可以在 2D UI 階層中直接呼叫 Subspace。不過，請務必瞭解在階層中叫用 Subspace 的影響。

關於子空間階層

頂層子空間是應用程式叫用的最外層子空間。請為頂層子空間使用 ApplicationSubspace 可組合項，但如果您只在應用程式中使用子空間可組合項，最外層的 Subspace 可組合項將會是頂層子空間。根據預設，這個頂層子空間會受限於觀看應用程式的建議空間，通常是放置應用程式空間版面配置和 SpatialPanel 的位置。如果您需要變更頂層子空間的邊界，請將不同的 VolumeConstraints 傳遞至 ApplicationSubspace。

不過，如果您在包含頂層子區塊的面板中，在 2D UI 階層中巢狀結構另一個子區塊，該巢狀結構子區塊的行為會有所不同。

巢狀子空間與頂層 Subspace 有兩個主要差異：

  • 這些元件會參與其叫用的 2D 版面配置。也就是說，子區塊的高度和寬度會受到其 2D 父項版面配置的高度和寬度限制。
  • 這些元素的行為就像是所叫用的實體的子項。也就是說，如果您呼叫巢狀在 SpatialPanel 中的 Subspace 可組合項，該子區域就是呼叫時所屬 SpatialPanel 的子項。

巢狀子空間的這些行為可啟用以下功能：

  • 使用父項實體移動子項
  • 使用偏移量 SubspaceModifier 偏移子項的位置
  • 呈現 3D 物件，讓其懸停在 2D UI 上方，並與 2D 版面配置中適當空間的高度和寬度相符

在應用程式中新增子空間

以下程式碼範例說明如何在應用程式中新增頂層和巢狀子集：

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