在應用程式中新增子區

適用的 XR 裝置

本指南可協助您為這類 XR 裝置打造體驗。

瞭解 XR 裝置類型 →

瞭解 XR 裝置類型 →

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

如要進一步瞭解空間版面配置，以及可在子空間中使用的元件，請參閱「空間化元件」。

關於子空間階層

頂層 Subspace 是應用程式叫用的最外層子空間。每次呼叫 Subspace 方法時，都會建立新的獨立空間 UI 階層。不會沿用任何巢狀父項 Subspace 的空間位置、方向或比例。

如要在 SpatialPanel、Orbiter、SpatialPopup 或其他元件中建立內嵌或巢狀 Subspace，請使用 PlanarEmbeddedSubspace。

PlanarEmbeddedSubspace 與 Subspace 有兩項主要差異：

• 它們會參與叫用它們的 2D 版面配置。這表示子空間的高度和寬度會受限於 2D 上層布局的高度和寬度。
• 其行為與叫用它們的實體的子項相同。也就是說，如果您呼叫巢狀結構在 SpatialPanel 內部的子空間可組合項，該子空間就是呼叫它的 SpatialPanel 的子項。

PlanarEmbeddedSubspace 的這些行為可啟用下列功能：

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

調整子空間的版面配置

在 Android XR 上，應用程式的版面配置預設會繫結至完整空間模式中 Subspace 的 VolumeConstraints。因此，請考量使用者可用的可見空間，並據此調整版面配置。recommendedContentBoxInFullSpace 會提供 ActivitySpace 內定界框的特定尺寸，以便將內容放置在使用者視野內。

應用程式的主要內容應位於這個方塊內。如果內容必須超出建議範圍，請考慮採用鼓勵使用者移動頭部探索空間的版面配置。您可以套用自訂的大小修飾符 (例如 SubspaceModifier.requiredSizeIn)，覆寫 recommendedContentBoxInFullSpace 的預設限制。如要設定無限制行為，請設定 allowUnboundedSubspace = true。

使用目前的工作階段呼叫 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。