空间面板

适用的 XR 设备

本指南可帮助您为以下类型的 XR 设备打造优质体验。

了解 XR 设备类型 →

扩展现实头戴设备

有线扩展现实眼镜

了解 XR 设备类型 →

SpatialPanel 是一种子空间可组合项，可让您显示应用的内容，例如，您可以在空间面板中显示视频播放、静态图片或任何其他内容。

图 1：空间界面面板示例。

您可以使用 SubspaceModifier 更改空间面板的大小、行为和位置

创建空间面板

以下示例展示了如何创建空间面板。

注意： 请在 Android 清单中添加 enableOnBackInvokedCallback="True"，以确保 SpatialPanel 能够正确接收 GNav 返回事件。

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

@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.kt

代码要点

• 由于 SpatialPanel API 是子空间可组合项，因此您必须在 Subspace 中调用它们。在子空间之外调用它们会抛出异常。
• 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")
            }
        }
    }
}
SpatialLayout.kt

@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
        )
    }
}
SpatialLayout.kt

代码要点

• SpatialRow、SpatialColumn、SpatialBox 和 SpatialSpacer 都是子空间可组合项，必须放置在子空间内。
• 使用 SubspaceModifier 自定义布局。
• 对于一行中包含多个面板的布局，我们建议使用 SubspaceModifier 设置 825dp 的曲线半径，以便面板环绕用户。如需了解详情，请参阅我们的设计指南。

创建自定义面板和布局

如需创建 Compose for XR 不支持的自定义面板，您可以使用 SceneCore API 直接处理 PanelEntity 实例和场景图。