仲裁者

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

Orbiter 是空間化元件，可附加至對應的空間面板或空間版面配置元件，例如 SpatialColumn、SpatialRow 或 SpatialBox。Orbiter 通常包含與錨定實體相關的導覽和關聯動作項目。舉例來說，如果您建立空間面板來顯示影片內容，可以在 Orbiter 中加入影片播放控制項。

圖 1：軌道飛行器範例。

建立軌道飛行器

如下例所示，在 SpatialPanel 的 2D 版面配置中呼叫 Orbiter，包裝導覽等使用者控制項。這樣做會從 2D 版面配置中擷取這些元素，並根據您的設定附加至空間面板。

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

@Composable
fun OrbiterExample() {
    Orbiter(
        position = OrbiterPosition.BottomCenter(
            verticalEdgeAlignment = OrbiterPosition.EdgeAlignment.Outside,
            offset = DpVolumeOffset(y = 96.dp)
        ),
    ) {
        Surface(Modifier.clip(CircleShape)) {
            Row(
                Modifier
                    .background(color = Color.Black)
                    .height(100.dp)
                    .width(600.dp),
                horizontalArrangement = Arrangement.Center,
                verticalAlignment = Alignment.CenterVertically
            ) {
                Text(
                    text = "Orbiter",
                    color = Color.White,
                    fontSize = 50.sp
                )
            }
        }
    }
}

程式碼重點

  • 由於軌道器是空間 UI 元件，因此程式碼可在 2D 或 3D 版面配置中重複使用。在 2D 版面配置中，應用程式只會算繪 Orbiter 內的內容，並忽略 Orbiter 本身。
  • 如要進一步瞭解如何使用及設計軌道，請參閱設計指南。

將軌道器錨定至空間面板和版面配置

您可以將軌道器錨定至 Compose 中宣告的 SpatialPanel 和空間版面配置元件。這包括在 UI 元素的空間版面配置中宣告軌道器，例如 SpatialRow、SpatialColumn 或 SpatialBox。軌道器會錨定在最接近宣告位置的父項。

軌道器的行為取決於宣告位置：

  • 在包裝於 SpatialPanel 的 2D 版面配置中 (如前述程式碼片段所示)，軌道器會錨定至該 SpatialPanel。
  • 在 Subspace 中，軌道器會固定在最近的上層實體，也就是宣告軌道器的空間版面配置。

以下範例說明如何將 Orbiter 錨定至空間列：

Subspace {
    SpatialRow {
        Orbiter(
            position = OrbiterPosition.TopCenter(
                verticalEdgeAlignment = OrbiterPosition.EdgeAlignment.Outside,
                offset = DpVolumeOffset(y = 8.dp)
            ),
            shape = SpatialRoundedCornerShape(size = CornerSize(50))
        ) {
            Text(
                "Hello World!",
                style = MaterialTheme.typography.titleMedium,
                modifier = Modifier
                    .background(Color.White)
                    .padding(16.dp)
            )
        }
        SpatialPanel(
            SubspaceModifier
                .height(824.dp)
                .width(1400.dp)
        ) {
            Box(
                modifier = Modifier
                    .background(Color.Red)
            )
        }
        SpatialPanel(
            SubspaceModifier
                .height(824.dp)
                .width(1400.dp)
        ) {
            Box(
                modifier = Modifier
                    .background(Color.Blue)
            )
        }
    }
}

程式碼重點

  • 在 2D 版面配置外宣告軌道器時，軌道器會固定在最近的上層實體。在本範例中，軌道器會錨定在宣告的 SpatialRow 頂端。
  • SpatialRow、SpatialColumn、SpatialBox 等空間版面配置都有相關聯的無內容實體。因此，在空間版面配置中宣告的軌道器會錨定至該版面配置。