空間パネル

対象となる XR デバイス
このガイダンスは、次のようなタイプの XR デバイス向けのエクスペリエンスを構築する際に役立ちます。
XR デバイスのタイプについて →
XR ヘッドセット
有線 XR グラス
XR デバイスのタイプについて →

A SpatialPanel is a subspace composable that lets you display your app's content–for example, you could display video playback, still images, or any other content in a spatial panel.

図 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 内で呼び出す必要があります。サブスペース外で呼び出すと、例外がスローされます。
  • 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
        )
    }
}

コードに関する主なポイント

  • SpatialRow、SpatialColumn、SpatialBox、SpatialSpacer はすべてサブスペース コンポーザブルであり、サブスペース内に配置する必要があります。
  • SubspaceModifier を使用してレイアウトをカスタマイズします。
  • 複数のパネルが並んだレイアウトでは、SubspaceModifier を使用して 825 dp の曲線半径を設定し、パネルがユーザーを囲むようにすることをおすすめします。詳しくは、設計に関するガイダンスをご覧ください。

カスタムパネルとレイアウトを作成する

Compose for XR でサポートされていないカスタムパネルを作成するには、SceneCore API を使用して、PanelEntity インスタンスとシーングラフを直接操作します。