공간 패널

적용 가능한 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 내에서 호출해야 합니다. 하위 공간 외부에서 호출하면 예외가 발생합니다.
  • 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를 사용하여 곡선 반경을 825dp로 설정하는 것이 좋습니다. 자세한 내용은 디자인 안내를 참고하세요.

맞춤 패널 및 레이아웃 만들기

Compose for XR에서 지원하지 않는 맞춤 패널을 만들려면 SceneCore API를 사용하여 PanelEntity 인스턴스 및 장면 그래프를 직접 사용하면 됩니다.