空間面板

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

SpatialPanel 是子空間可組合項，可讓您顯示應用程式內容，例如在空間面板中顯示影片播放、靜態圖片或任何其他內容。

圖 1：空間 UI 面板範例。

您可以使用 SubspaceModifier 變更空間面板的大小、行為和位置

建立空間面板

以下範例說明如何建立空間面板。

Subspace {
    SpatialPanel(
        SubspaceModifier
            .height(824.dp)
            .width(1400.dp)
            .movable()
            .resizable(),
    ) {
        SpatialPanelContent()
    }
}

@Composable
fun SpatialPanelContent() {
    Box(
        Modifier
            .background(color = Color.Black)
            .height(500.dp)
            .width(500.dp),
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = "Spatial Panel",
            color = Color.White,
            fontSize = 25.sp
        )
    }
}

程式碼重點

  • 由於 SpatialPanel API 是子空間可組合函式，因此您必須在 Subspace 中呼叫這些 API。如果在子空間外呼叫，會擲回例外狀況。
  • SpatialPanel 的大小已使用 SubspaceModifier 上的 height 和 width 規格設定。如果省略這些規格，面板的大小就會由內容的測量結果決定。
  • 新增 movable 子空間修飾符，允許使用者移動面板。
  • 新增 resizable 子空間修飾符，允許使用者調整面板大小。
  • 如要進一步瞭解大小和位置，請參閱空間面板設計指南。如要進一步瞭解程式碼導入作業，請參閱參考文件。

movable 修飾符的運作方式

當使用者將面板移開時，movable 修飾符預設會縮放面板，縮放方式與系統在主空間中調整面板大小的方式類似。所有子項內容都會沿用這項行為。如要停用這項功能，請將 shouldScaleWithDistance 參數設為 false。

在空間版面配置中新增多個空間面板

您可以使用 SpatialRow、SpatialColumn、SpatialBox 和 SpatialSpacer 建立多個空間面板，並將其放置在空間版面配置中。

圖 2：空間版面配置中有多個空間面板的範例。

以下程式碼範例說明如何執行這項操作。

Subspace {
    SpatialRow {
        SpatialColumn {
            SpatialPanel(SubspaceModifier.height(250.dp).width(400.dp)) {
                SpatialPanelContent("Top Left")
            }
            SpatialPanel(SubspaceModifier.height(200.dp).width(400.dp)) {
                SpatialPanelContent("Middle Left")
            }
            SpatialPanel(SubspaceModifier.height(250.dp).width(400.dp)) {
                SpatialPanelContent("Bottom Left")
            }
        }
        SpatialColumn {
            SpatialPanel(SubspaceModifier.height(250.dp).width(400.dp)) {
                SpatialPanelContent("Top Right")
            }
            SpatialPanel(SubspaceModifier.height(200.dp).width(400.dp)) {
                SpatialPanelContent("Middle Right")
            }
            SpatialPanel(SubspaceModifier.height(250.dp).width(400.dp)) {
                SpatialPanelContent("Bottom Right")
            }
        }
    }
}

@Composable
fun SpatialPanelContent(text: String) {
    Column(
        Modifier
            .background(color = Color.Black)
            .fillMaxSize(),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        Text(
            text = "Panel",
            color = Color.White,
            fontSize = 15.sp
        )
        Text(
            text = text,
            color = Color.White,
            fontSize = 25.sp,
            fontWeight = FontWeight.Bold
        )
    }
}

程式碼重點

建立自訂面板和版面配置

如要建立 Compose for XR 不支援的自訂面板，可以使用 SceneCore API，直接操作 PanelEntity 執行個體和場景圖。