이 페이지는 Cloud Translation API를 통해 번역되었습니다.

XR용 Jetpack Compose

API 참조
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

Android XR의 공간 기능을 활용하는 공간 UI 레이아웃을 선언적으로 빌드합니다.

최근 업데이트	안정화 버전	출시 후보 버전	베타 버전	알파 버전
2025년 7월 30일	-	-	-	1.0.0-alpha05

종속 항목 선언

XR Compose의 종속 항목을 추가하려면 프로젝트에 Google Maven 저장소를 추가해야 합니다. 자세한 내용은 Google Maven 저장소를 읽어보세요.

다음과 같이 앱 또는 모듈의 build.gradle 파일에 필요한 아티팩트의 종속 항목을 추가합니다.

Groovy

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha05"

    // Use to write unit tests
    testImplementation "androidx.xr.compose:compose-testing:1.0.0-alpha05"
}

Kotlin

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha05")

    // Use to write unit tests
    testImplementation("androidx.xr.compose:compose-testing:1.0.0-alpha05")
}

종속 항목에 관한 자세한 내용은 빌드 종속 항목 추가를 참고하세요.

의견

제출하신 의견은 Jetpack을 개선하는 데 도움이 됩니다. 새로운 문제를 발견하거나 라이브러리 개선을 위한 아이디어가 있다면 Google에 알려 주세요. 새 문제를 제출하기 전에 이 라이브러리의 기존 문제를 살펴보시기 바랍니다. 별표 버튼을 클릭하여 기존 문제에 투표할 수 있습니다.

새로운 문제 제출하기

자세한 내용은 Issue Tracker 문서를 참고하세요.

버전 1.0

버전 1.0.0-alpha05

2025년 7월 30일

androidx.xr.compose:compose:1.0.0-alpha05 및 androidx.xr.compose:compose-testing:1.0.0-alpha05이 출시되었습니다. 버전 1.0.0-alpha05에는 이 커밋이 포함되어 있습니다.

새로운 기능

SubspaceComposable 주석 클래스가 공개되었습니다. (Ic2a34, b/399432430)
180도 및 360도 구체를 나타내는 두 개의 새로운 SpatialExternalSurface 컴포저블 (I40ef2, b/391705799)
SubspaceModifier.aspectRatio 추가 (Ide5ab, b/399729509, b/414762147)
SceneCore와 XR용 Compose 간의 상호 운용성을 개선하기 위해 SceneCoreEntity API가 추가되었습니다. (I50bb3, b/423020989)
GravityAlignedsubspace API를 제공하여 크기 조정되지 않은 GravityAligned 기능을 지원했습니다. (I07359)

API 변경사항

SpatialDialog()는 SpatialDialogProperties.dismissOnBack 누르기 구성을 따릅니다. (Ib453b, b/416797132)
미터로 표현되므로 minimumPanelDimension를 새로운 기본 측정기준 크기인 Dimensions(0.1f, 0.1f, 0.1f)로 업데이트합니다. (Ib852a)
이제 하위 스페이스와 오비터는 홈 스페이스와 앱이 백그라운드에 있을 때 내부 상태를 유지합니다. 홈 스페이스 모드에서도 서브스페이스는 풀 스페이스 모드로 전환할 준비를 위해 장면을 설정합니다. (I40317, b/416037751)
이제 앱이 백그라운드에 있을 때 SpatialDialogs가 상태를 유지합니다. (I6aa56)
이제 ApplicationSubspace가 시스템에서 권장하는 크기와 위치를 상속합니다. (I4565f, b/418834194)
SubspaceComposable이 SubspaceComposable이 아닌 컨텍스트에서 사용될 때 더 나은 오류 메시지를 추가하고 오류를 더 일찍 트리거했습니다. (Iee2ae, b/416484684)
컴포저블 API를 잘못 사용할 때 경고가 간과되는 경우가 많으므로 ExperimentalSubspaceVolumeApi를 경고에서 오류로 업데이트 (I427aa, b/424864286)
이제 서브스페이스와 ApplicationSubspace이 recommendedContentBoxInFullSpace에 의해 제한됩니다. 이전에는 SpatialUser의 시야에 의해 제한되었습니다. (I41015, b/423074142)
하드 코딩된 크기를 더 이상 사용하지 않도록 최소 크기를 사용하도록 SpatialElevation 업데이트 (I2dbe6, b/427785338)
키 변수가 수정될 때 업데이트되도록 SpatialAcitivityPanel를 스크림하는 방식 업데이트 (I0f64d, b/427999029)
기본 제약 조건 값을 동일한 값으로 설정하는 대신 VolumeConstraints.Unbounded를 삭제합니다. (Ie24ec, b/407938414)
SpatialFeatheringSize가 더 이상 공개되지 않습니다. (I1c15b, b/399432430)
Compose의 Placeable와 구분하기 위해 XR Placeable의 이름을 SubspacePlaceable로 변경했습니다. (I74874)
Orbiter 설정을 삭제하고 shouldRenderInNonSpatial를 새 매개변수로 추가 또한 EdgeOffset 클래스를 삭제하고 Orbiter() 함수를 통합하기 위해 orbiterOffsetType을 새 매개변수로 추가합니다. OrbiterEdge의 이름을 ContentEdge으로 변경합니다. (Iebf3d)
Compose의 Measurable 유형과 유형을 구분하기 위해 Measurable의 이름을 SubspaceMeasurable로 변경했습니다. (I9726c)
MeasureResult를 SubspaceMeasureResult로 이름을 바꿨습니다. (I9f34d)
Compose의 setContent을 Subspace 컴포저블과 함께 사용하기 위해 setSubspaceContent API가 삭제되었습니다. (Ifff4c, b/421427391, b/421427391)
MeasurePolicy에서 SubspaceMeasurePolicy로 이름이 변경되었습니다. (I37a9b, b/422553904)
기본값이 없으면 멤버를 추가할 수 없으므로 SubspaceSemanticsInfo를 봉인된 인터페이스로 전환 (I372f9, b/423704068)
SpatialExternalSurface 문서를 업데이트하고 ContentSecurityLevel의 이름을 SurfaceProtection로 바꿨습니다. (I3c460, b/420982808)
고정할 수 있는 이동 가능한 수정자의 오버로드된 생성자를 제공했습니다. (Ic0c70)
이제 개발자가 앵커의 위, 아래, 왼쪽, 오른쪽에 툴팁을 배치할지 제어할 수 있도록 툴팁의 위치 제공자를 추가했습니다. 더 많은 맞춤 모양을 제공할 수 있도록 캐럿의 모양을 가져오는 API 추가 (Ie513c, b/374766087, b/418854637)
CoreEntity이(가) PublishedApi으로 삭제됨(Ifee05)

버그 수정

렌더링될 때 SpatialDialog이 깜박이는 문제를 수정했습니다. (Ife73c, b/401619909)
SpatialDialog가 활동 패널을 스크림할 수 없는 문제를 수정했습니다. (I8ca6c, b/367442109)
XR 대화상자에 일부 콘텐츠가 표시되지 않는 문제 수정 (I17cd5, b/418062437)
콘텐츠 내부를 클릭하면 SpatialPopup가 닫히는 문제를 수정했습니다. (If262c, b/417245722)
resizable().movable()을 연결할 때 SpatialPanel이 새 크기로 올바르게 크기를 조절하지 못하는 문제가 수정되었습니다. (I02ee3, b/422264230)
SpatialComposeVideoPlayer에서 topBar이 메뉴와 겹치는 문제 수정 (Id33bc, b/427168167)
모서리 반지름이 렌더링되지 않는 문제 수정 (I975fe, b/428261830)

버전 1.0.0-alpha04

2025년 5월 7일

androidx.xr.compose:compose:1.0.0-alpha04 및 androidx.xr.compose:compose-testing:1.0.0-alpha04이 출시되었습니다. 버전 1.0.0-alpha04에는 이러한 커밋이 포함되어 있습니다.

새로운 기능

맞춤 SubspaceModifier 유형이 컴포지션 로컬 값에 액세스할 수 있도록 CompositionLocalConsumerSubspaceModifierNode 인터페이스를 추가했습니다.
Compose AndroidView 구현 스타일을 따르고 이전 ViewBased SpatialPanel를 지원 중단하는 새로운 SpatialPanel API가 추가되었습니다.
무한 제약 조건을 나타내는 VolumeConstraints.Unbounded 컴패니언 객체를 추가했습니다.
공간화된 오디오 소스를 허용하도록 SubspaceModifier.onPointSourceParams를 추가했습니다.
공개 ApplicationSubspace가 추가되어 앱이 공간 콘텐츠를 렌더링할 수 있는 3D 영역을 정의하는 선택적 VolumeConstraints를 제공합니다. 기본적으로 제약 조건이 지정되지 않으면 하위 공간은 SpatialUser의 현재 시야가 너비와 높이로 제한됩니다. 사용자는 시야를 확인할 수 없는 경우 사용할 제약 조건을 제공할 수 있습니다. 그렇지 않으면 기본 시야 너비 및 높이 값이 사용됩니다.
스테레오스코피 콘텐츠를 렌더링하는 데 사용할 수 있는 SpatialExternalSurface를 추가했습니다. SpatialExternalSurface는 수정자 (알파 제외)와 가장자리 페더링 효과로 맞춤설정할 수 있습니다.
사용자가 공간 포인터의 아이콘을 설정할 수 있는 새로운 pointerHoverIcon 하위 공간 수정자가 추가되었습니다.

API 변경사항

모든 Jetpack XR 패키지에서 RequiresApi(34) 제한을 삭제했습니다. Jetpack XR은 현재 API 수준 34 이상의 기기에서만 사용할 수 있으므로 이 제한은 중복되었습니다. (Iae0f8)
Kotlin 2.0으로 출시된 프로젝트를 사용하려면 KGP 2.0.0 이상이 필요합니다. (Idb6b5)
이제 활동이 삽입되지 않은 공간 패널에서 뒤로 처리가 작동합니다. 뒤로 처리가 작동하려면 Android 매니페스트에 android:enableOnBackInvokedCallback="true"를 지정해야 합니다.
이제 백핸들링이 공간 다이얼로그에서 작동합니다. 뒤로 처리가 작동하려면 Android 매니페스트에 android:enableOnBackInvokedCallback="true"를 지정해야 합니다.
이제 Compose 기반 및 뷰 기반 SpatialPanel가 콘텐츠에 따라 크기를 조정할 수 있습니다.
이제 개발자는 자체 맞춤 SpatialElevationLevel 값을 설정할 수 있으며 사전 정의된 수준으로 제한되지 않습니다.
이제 elevation 매개변수를 통해 오비터 고도 수준을 맞춤설정할 수 있습니다.
이제 하위 공간이 기본적으로 SpatialUser의 시야에 의해 너비와 높이로 제한될 수 있습니다. 시야를 확인할 수 없는 경우 기본 시야 너비 및 높이 값이 사용됩니다.
Movable 수정자에 새로운 콜백 onMoveStart 및 onMoveEnd을 추가했습니다. 사용자가 이동 가능한 수정자를 사용하여 하위 공간 컴포저블을 이동하기 시작하고 이동을 종료하면 onMoveStart 및 onMoveEnd 콜백이 호출됩니다.
SpatialRow, SpatialPanel과 같은 공간 API에서 name 매개변수가 삭제되었습니다. 공간 컴포즈 트리를 디버깅하려면 대신 SubspaceModifier.testTag를 사용하세요.
spatialElevationLevel 및 content만 있는 지원되지 않는 SpatialPopup 오버로드가 삭제되었습니다. onDimissRequest를 지원하는 인터페이스를 사용하세요.
Movable 수정자의 onPoseChange 콜백이 삭제되었습니다. 대신 onMove를 사용합니다.
SubspaceModifiers는 분리되었거나 현재 분리 중인 경우 더 이상 효과를 적용하지 않습니다.
기존 SpatialRow API가 SpatialRow 및 SpatialCurvedRow로 분할되었습니다. 이전에 SpatialRow의 curveRadius 매개변수를 사용했다면 이제 동일한 동작을 제공하는 SpatialCurvedRow를 대신 사용하세요.
MainPanel 및 ActivityPanel은 유사한 최신 시스템 이미지에서 실행될 때 더 이상 제목 표시줄이 없습니다.
이제 알파 및 스케일 수정자를 스택할 수 있으며 최종 적용된 알파 또는 스케일 값에 값이 곱해집니다.
이동 가능한 수정자의 onPoseChange 콜백이 더 부드러운 포즈 이동을 실행하도록 최적화되었습니다.
이제 이동 가능 및 크기 조절 가능 수정자가 상태 변경이 리컴포지션을 트리거하도록 기본 스레드에서 콜백을 실행합니다.
SubspaceLayout의 상태 변경이 리레이아웃을 트리거하도록 레이아웃 및 측정 단계에 상태 관찰을 추가했습니다.
기존 수정자를 더 잘 재사용할 수 있도록 최적화된 수정자 체인 업데이트

버그 수정

SpatialDialog가 표시될 때 스크림이 중지되었습니다. (Ic4594)
수정자 노드가 분리된 동안 이루어진 레이아웃 요청이 이제 무시됩니다.
이동 가능 및 크기 조절 가능 수정자로 트리거되는 레이아웃 재조정 단계를 삭제했습니다.
MainPanel() 컴포저블에서 두 측정기준 중 하나가 직접 또는 레이아웃 계산(예: SpatialRow/SpatialColumn 계산) 중에 0으로 설정될 때 발생하는 비정상 종료가 수정되었습니다. 이제 패널이 숨겨집니다. 이 수정사항은 레이아웃 단계의 비정상 종료를 구체적으로 해결합니다. 사용자 상호작용을 통해 패널을 0으로 크기를 조절하는 것은 별도로 처리됩니다. 숨겨진 패널에 UI 어포던스가 없습니다.
크기 조절 가능한 수정자의 maintainAspectRatio 문제가 수정되었습니다. 이제 가로세로 비율이 유지됩니다.
단일 프레임에서 잘못 배치되는 중첩된 하위 스페이스 문제가 해결되었습니다.
둥근 모서리가 적용되어야 할 때 적용되지 않는 문제가 수정되었습니다.
NestedSubspaces가 잘못된 위치에 한 프레임 동안 더 이상 표시되지 않습니다.

버전 1.0.0-alpha03

2025년 2월 26일

androidx.xr.compose:compose:1.0.0-alpha03 및 androidx.xr.compose:compose-testing:1.0.0-alpha03은 마지막 알파 이후 눈에 띄는 변경사항 없이 출시되었습니다. 버전 1.0.0-alpha03에 포함된 커밋을 확인하세요.

버전 1.0.0-alpha02

2025년 2월 12일

androidx.xr.compose:compose:1.0.0-alpha02 및 androidx.xr.compose:compose-testing:1.0.0-alpha02이 출시되었습니다. 버전 1.0.0-alpha02에는 이 커밋이 포함되어 있습니다.

새로운 기능

이제 활동 패널은 공간 대화상자가 활성화되면 콘텐츠를 스크림할 수 있습니다.
이제 Orbiter API를 SubspaceComposable 컨텍스트에서 사용할 수 있으며, 오비터가 가장 가까운 SubspaceLayout 기반 컴포저블 상위에 연결됩니다.
맞춤 위치 기반 수정자를 허용하기 위해 LayoutCoordinatesAwareModifierNode가 도입되었습니다.
SubspaceModifier.Node에 연결/분리 수명 주기 메서드가 추가되었습니다.
이동 가능한 수정자에 scaleWithDistance를 추가했습니다. scaleWithDistance가 사용 설정되면 이동된 하위 공간 요소가 늘어나거나 줄어듭니다. 또한 이동 전의 명시적 스케일도 유지됩니다.

API 변경사항

SpatialCapabilities을 위해 SessionCallbackProvider이 삭제되었습니다.

기타 변경사항

minSDK을 24로 줄였습니다. 모든 Jetpack XR API는 런타임에 API 34가 계속 필요합니다.
Orbiter EdgeOffset.inner, EdgeOffset.outer, EdgeOffset.overlap 생성자가 더 이상 @Composable 메서드가 아니므로 컴포저블이 아닌 컨텍스트에서 사용할 수 있습니다.
최신 UX 사양에 맞게 공간 고도 수준을 업데이트합니다.
SubspaceSemanticsInfo 인터페이스를 MeasurableLayout에 구현합니다.
SubspaceModifierElement에서 SubspaceModifierNodeElement로 이름이 변경되었습니다.

버그 수정

SubspaceModifier 주문을 안정화하기 위한 수정사항 SubspaceModifier의 동작이 더 안정적이어야 합니다. 이제 오프셋, 회전, 크기 조절, 이동 가능, 크기 조절 가능 수정자를 순서에 상관없이 사용할 수 있습니다.

버전 1.0.0-alpha01

2024년 12월 12일

androidx.xr.compose:compose-*1.0.0-alpha01이 출시되었습니다.

초기 출시의 기능

XR용 Jetpack Compose의 초기 개발자 출시 기존 2D 앱을 XR로 포팅하든 처음부터 새로운 XR 앱을 만들든 행, 열과 같은 친숙한 Compose 개념을 사용하여 XR에서 공간 UI 레이아웃을 만드세요. 이 라이브러리는 기존 2D Compose 또는 뷰 기반 UI를 공간 레이아웃에 배치할 수 있는 공간 패널, 오비터와 같은 하위 공간 및 공간 컴포저블을 제공합니다. UI를 기준으로 3D 모델과 같은 SceneCore 엔티티를 배치할 수 있는 Volume 하위 공간 컴포저블을 소개합니다. 자세한 내용은 개발자 가이드를 참고하세요.
- Subspace: 이 컴포저블은 앱의 UI 계층 구조 내 어디에나 배치할 수 있으므로 파일 간 컨텍스트를 잃지 않고 2D 및 공간 UI의 레이아웃을 유지할 수 있습니다. 이렇게 하면 전체 UI 트리를 통해 상태를 호이스팅하거나 앱을 재설계하지 않고도 XR과 기타 폼 팩터 간에 기존 앱 아키텍처와 같은 항목을 더 쉽게 공유할 수 있습니다.
- SpatialPanel: 공간 패널은 앱 콘텐츠를 표시할 수 있는 하위 공간 컴포저블입니다. 예를 들어 공간 패널에 동영상 재생, 정지 이미지 또는 기타 콘텐츠를 표시할 수 있습니다.
- Orbiter: Orbiter는 공간 UI 구성요소입니다. 해당 공간 패널에 연결되도록 설계되었으며 해당 공간 패널과 관련된 탐색 및 상황별 작업 항목이 포함되어 있습니다. 예를 들어 동영상 콘텐츠를 표시하는 공간 패널을 만든 경우, 오비터 내에 동영상 재생 컨트롤을 추가할 수 있습니다.
- 볼륨: UI를 기준으로 3D 모델과 같은 SceneCore 엔티티를 배치합니다.
공간 레이아웃: SpatialRow, SpatialColumn, SpatialBox, SpatialLayoutSpacer를 사용하여 여러 공간 패널을 만들고 공간 레이아웃 내에 배치할 수 있습니다. SubspaceModifier를 사용하여 레이아웃을 맞춤설정합니다.
공간 UI 구성요소: 이러한 요소는 2D UI에서 재사용할 수 있으며 공간 기능이 사용 설정된 경우에만 공간 속성이 표시됩니다.
- SpatialDialog: 패널이 z축으로 약간 뒤로 밀려 올라간 대화상자가 표시됩니다.
- SpatialPopUp: 패널이 z축으로 약간 뒤로 밀려 올라간 팝업을 표시합니다.
- SpatialElevation: SpatialElevationLevel을 설정하여 고도를 추가할 수 있습니다.
SpatialCapabilities: 사용자가 앱이나 시스템과 상호작용할 때 공간 기능이 변경될 수 있으며, 앱 자체에서 변경될 수도 있습니다(예: 홈 스페이스 또는 전체 스페이스로 이동). 문제를 방지하려면 앱에서 LocalSpatialCapabilities.current를 확인하여 현재 환경에서 지원되는 API를 확인해야 합니다. isSpatialUiEnabled: 공간 UI 요소 (예: SpatialPanel) isContent3dEnabled: 3D 객체 isAppEnvironmentEnabled: 환경 isPassthroughControlEnabled: 애플리케이션이 패스스루 상태를 제어할 수 있는지 여부 isSpatialAudioEnabled: 서라운드 오디오

알려진 문제

현재 XR에 Jetpack Compose를 사용하려면 minSDK 30이 필요합니다. 이 문제를 해결하려면 minSDK가 23인 상태에서 빌드하고 실행할 수 있도록 다음 매니페스트 항목 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>를 추가하세요.
현재 Jetpack XR 앱은 AndroidManifest에서 android.permission.SCENE_UNDERSTANDING 권한을 요청해야 합니다.
앱이 매니페스트에서 PROPERTY_XR_ACTIVITY_START_MODE 속성을 사용하여 전체 공간으로 직접 실행되면 활동/애플리케이션이 전체 공간으로 전환되기 전에 홈 공간에서 처음 열립니다.
볼륨 컴포저블의 glTF가 처음에 잘못된 위치에서 깜박일 수 있습니다.
크게 이동한 패널에서 SpatialDialog를 사용하면 콘텐츠가 잘못된 방향으로 푸시됩니다.