在應用程式中新增子區

適用的 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
XR 頭戴式裝置
有線 XR 眼鏡
瞭解 XR 裝置類型 →

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

您可以使用 SpatialPanel、SpatialRow 和 SpatialColumn 等子空間可組合項建立版面配置，並在 3D 空間中放置 2D 內容。如要放置 3D 內容，請使用適當的 Subspace Composable，例如 3D 模型的 SceneCoreEntity 和立體圖像的 SpatialExternalSurface。部分 XR 元件 (例如 Orbiter 或 SpatialDialog) 是標準的 2D 可組合函式，可在 2D UI 階層中的任何位置使用，但 SubspaceComposable 必須在應用程式的子空間中叫用。如要執行這項操作，請使用 Subspace 子空間可組合函式。

關於子空間階層

最上層的 Subspace 是應用程式叫用的最外層子空間。每次呼叫 Subspace 都會建立新的獨立空間 UI 層級。不會繼承任何父項的空間位置、方向或比例，Subspace而是巢狀結構。

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

PlanarEmbeddedSubspace 與 Subspace 有兩項主要差異：

  • 這些檢視區塊會參與叫用它們的 2D 版面配置。也就是說，子空間的高度和寬度會受到 2D 上層布局的高度和寬度限制。
  • 這些函式會以呼叫所在實體的子項身分運作。也就是說，如果您呼叫巢狀內嵌於 SpatialPanel 中的子空間可組合項，該子空間就是呼叫所在 SpatialPanel 的子項。

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

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

調整子空間的版面配置

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

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

使用目前的 Session 呼叫 recommendedContentBoxInFullSpace，視需要取得這些特定維度。請參閱以下範例：

val session = LocalSession.current
session?.scene?.activitySpace?.recommendedContentBoxInFullSpace

為應用程式新增子空間

以下程式碼範例說明如何在應用程式中新增 Subspace 和 PlanarEmbeddedSubspace：

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

@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 和 PlanarEmbeddedSubspace 的完整參考文件。