Jetpack Compose untuk XR

Buat tata letak UI spasial secara deklaratif yang memanfaatkan kemampuan spasial Android XR.
Update Terbaru Rilis Stabil Kandidat Rilis Rilis Beta Rilis Alfa
30 Juli 2025 - - - 1.0.0-alpha05

Mendeklarasikan dependensi

Untuk menambahkan dependensi pada XR compose, Anda harus menambahkan repositori Maven Google ke project Anda. Baca repositori Maven Google untuk mengetahui informasi selengkapnya.

Tambahkan dependensi untuk artefak yang diperlukan dalam file build.gradle bagi aplikasi atau modul Anda:

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")
}

Untuk informasi dependensi selengkapnya, lihat Menambahkan dependensi build.

Masukan

Masukan Anda membantu meningkatkan kualitas Jetpack. Beri tahu kami jika Anda menemukan masalah baru atau mempunyai masukan untuk meningkatkan kualitas library ini. Harap periksa masalah yang sudah diketahui dalam library ini sebelum membuat laporan baru. Anda dapat memberikan suara untuk masalah yang sudah diketahui dengan mengklik tombol bintang.

Laporkan masalah baru

Lihat dokumentasi Issue Tracker untuk informasi selengkapnya.

Versi 1.0

Versi 1.0.0-alpha05

30 Juli 2025

androidx.xr.compose:compose:1.0.0-alpha05 dan androidx.xr.compose:compose-testing:1.0.0-alpha05 dirilis. Versi 1.0.0-alpha05 berisi commit ini.

Fitur Baru

  • Menjadikan class anotasi SubspaceComposable publik. (Ic2a34, b/399432430)
  • Dua Composable SpatialExternalSurface baru yang merepresentasikan bola 180 dan 360 derajat. (I40ef2, b/391705799)
  • Menambahkan SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147)
  • Menambahkan API SceneCoreEntity untuk meningkatkan interoperabilitas antara SceneCore dan Compose untuk XR. (I50bb3, b/423020989)
  • Menyediakan API GravityAlignedsubspace untuk mendukung fitur And GravityAligned yang tidak diskalakan (I07359)

Perubahan API

  • SpatialDialog() akan mengikuti konfigurasi penekanan SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
  • Perbarui minimumPanelDimension ke Ukuran dimensi default baru Dimensions(0.1f, 0.1f, 0.1f) karena representasinya dalam Meter. (Ib852a)
  • Subruang dan Pengorbit kini akan mempertahankan status internalnya di ruang rumah dan saat aplikasi berada di latar belakang. Dalam mode ruang rumah, Subspace akan tetap menyiapkan adegannya untuk persiapan peralihan ke mode ruang penuh. (I40317, b/416037751)
  • SpatialDialogs kini akan mempertahankan statusnya saat aplikasi berada di latar belakang. (I6aa56)
  • ApplicationSubspace kini akan mewarisi skala dan posisi yang direkomendasikan dari sistem. (I4565f, b/418834194)
  • Menambahkan pesan error yang lebih baik dan memicu error lebih awal saat SubspaceComposable digunakan dalam konteks non-SubspaceComposable. (Iee2ae, b/416484684)
  • Memperbarui ExperimentalSubspaceVolumeApi dari Peringatan menjadi Error karena peringatan sering kali diabaikan saat menyalahgunakan API composable. (I427aa, b/424864286)
  • Subruang dan ApplicationSubspace kini dibatasi oleh recommendedContentBoxInFullSpace. Sebelumnya, kamera dibatasi oleh Field of View SpatialUser. (I41015, b/423074142)
  • Memperbarui SpatialElevation untuk menggunakan ukuran minimum agar tidak lagi menggunakan ukuran yang dikodekan secara permanen (I2dbe6, b/427785338)
  • Perbarui cara kita membuat layar redup SpatialAcitivityPanel untuk diperbarui saat variabel utama diubah. (I0f64d, b/427999029)
  • Hapus VolumeConstraints.Unbounded dan tetapkan nilai batasan default ke nilai yang setara. (Ie24ec, b/407938414)
  • SpatialFeatheringSize tidak lagi bersifat publik (I1c15b, b/399432430)
  • Mengganti nama XR Placeable menjadi SubspacePlaceable untuk membedakannya dari Placeable Compose. (I74874)
  • Menghapus setelan Orbiter dan menambahkan shouldRenderInNonSpatial sebagai parameter baru. Selain itu, menghapus class EdgeOffset dan menambahkan orbiterOffsetType sebagai parameter baru untuk menggabungkan Fungsi Orbiter(). Serta mengganti nama OrbiterEdge menjadi ContentEdge. (Iebf3d)
  • Mengganti nama Measurable menjadi SubspaceMeasurable untuk membedakan jenis dari jenis Measurable Compose. (I9726c)
  • Mengganti nama MeasureResult menjadi SubspaceMeasureResult (I9f34d)
  • Menghapus setSubspaceContent API dan menggantinya dengan setContent Compose dengan composable Subspace. (Ifff4c, b/421427391, b/421427391)
  • MeasurePolicy diganti namanya menjadi SubspaceMeasurePolicy. (I37a9b, b/422553904)
  • Ubah SubspaceSemanticsInfo menjadi antarmuka tertutup karena kita tidak akan dapat menambahkan anggota tanpa nilai default. (I372f9, b/423704068)
  • Memperbarui dokumentasi SpatialExternalSurface, mengganti nama ContentSecurityLevel menjadi SurfaceProtection (I3c460, b/420982808)
  • Menyediakan konstruktor kelebihan muatan untuk pengubah yang dapat dipindahkan yang memungkinkan penambatan. (Ic0c70)
  • Menambahkan penyedia posisi lainnya untuk tooltip sehingga kini developer dapat mengontrol apakah tooltip ditempatkan di atas, bawah, kiri, atau kanan anchor. Menambahkan API yang menerima Bentuk untuk penanda, sehingga lebih banyak bentuk kustom dapat diberikan. (Ie513c, b/374766087, b/418854637)
  • CoreEntity dihapus sebagai PublishedApi (Ifee05)

Perbaikan Bug

  • Memperbaiki masalah saat SpatialDialog berkedip saat dirender. (Ife73c, b/401619909)
  • Memperbaiki masalah saat SpatialDialog tidak dapat meng-scrim Panel Aktivitas. (I8ca6c, b/367442109)
  • Memperbaiki dialog XR yang tidak menampilkan beberapa konten (I17cd5, b/418062437)
  • Memperbaiki masalah saat SpatialPopup ditutup saat diklik di dalam konten. (If262c, b/417245722)
  • Memperbaiki masalah saat merangkai resizable().movable(), SpatialPanel gagal mengubah ukuran dengan benar ke ukuran baru. (I02ee3, b/422264230)
  • Memperbaiki topBar yang tumpang-tindih dengan menu di SpatialComposeVideoPlayer (Id33bc, b/427168167)
  • Memperbaiki radius sudut yang tidak dirender (I975fe, b/428261830)

Versi 1.0.0-alpha04

7 Mei 2025

androidx.xr.compose:compose:1.0.0-alpha04 dan androidx.xr.compose:compose-testing:1.0.0-alpha04 dirilis. Versi 1.0.0-alpha04 berisi commit ini.

Fitur Baru

  • Menambahkan antarmuka CompositionLocalConsumerSubspaceModifierNode untuk memungkinkan jenis SubspaceModifier kustom mengakses nilai lokal komposisi.
  • Menambahkan SpatialPanel API baru yang mengikuti gaya penerapan AndroidView compose dan menghentikan penggunaan ViewBased SpatialPanel sebelumnya.
  • Menambahkan objek pendamping VolumeConstraints.Unbounded yang merepresentasikan batasan tidak terbatas.
  • Menambahkan SubspaceModifier.onPointSourceParams untuk mengizinkan sumber audio spasial.
  • ApplicationSubspace publik telah ditambahkan, yang menawarkan VolumeConstraints opsional untuk menentukan area 3D tempat aplikasi dapat merender konten spasial. Secara default, jika tidak ada batasan yang ditentukan, Subspace akan dibatasi oleh lebar dan tinggi bidang pandang SpatialUser saat ini. Pengguna dapat memberikan batasan yang akan digunakan jika bidang pandang tidak dapat ditentukan. Jika tidak, nilai lebar dan tinggi bidang pandang default akan digunakan.
  • Menambahkan SpatialExternalSurface, yang dapat digunakan untuk merender konten stereoskopik. SpatialExternalSurface dapat disesuaikan dengan pengubah (kecuali alfa), dan efek feathering tepi.
  • Menambahkan Pengubah Subruang pointerHoverIcon baru yang memungkinkan pengguna menetapkan ikon untuk penunjuk spasial.

Perubahan API

  • Menghapus batasan RequiresApi(34) pada semua paket Jetpack XR. Pembatasan ini berlebihan karena Jetpack XR saat ini hanya tersedia di perangkat dengan level API 34+. (Iae0f8)
  • Project yang dirilis dengan Kotlin 2.0 memerlukan KGP 2.0.0 atau yang lebih baru untuk digunakan. (Idb6b5)
  • Penanganan kembali kini akan berfungsi di panel spasial tanpa aktivitas tersemat. Agar penanganan kembali berfungsi, Anda harus menentukan android:enableOnBackInvokedCallback="true" dalam manifes Android.
  • Penanganan kembali kini berfungsi pada dialog spasial. Agar penanganan kembali berfungsi, Anda harus menentukan android:enableOnBackInvokedCallback="true" dalam manifes Android.
  • SpatialPanel berbasis Compose dan berbasis View kini dapat menyesuaikan ukurannya berdasarkan kontennya.
  • Developer kini dapat menetapkan nilai SpatialElevationLevel kustom mereka sendiri dan tidak terbatas pada level yang telah ditentukan sebelumnya.
  • Tingkat elevasi pengorbit kini dapat disesuaikan melalui parameter elevation.
  • Subruang kini dapat dibatasi oleh bidang pandang SpatialUser dalam lebar dan tinggi secara default. Jika bidang pandang tidak dapat ditentukan, nilai lebar dan tinggi bidang pandang default akan digunakan.
  • Menambahkan callback baru onMoveStart dan onMoveEnd ke pengubah Movable. Callback onMoveStart dan onMoveEnd dipanggil saat pengguna mulai dan mengakhiri pemindahan composable subruang dengan pengubah yang dapat dipindahkan.
  • Parameter name telah dihapus dari API spasial seperti SpatialRow dan SpatialPanel. Untuk men-debug hierarki komposisi spasial, gunakan SubspaceModifier.testTag.
  • Menghapus kelebihan beban SpatialPopup yang tidak didukung yang hanya memiliki spatialElevationLevel dan content. Harap gunakan antarmuka yang mendukung onDimissRequest.
  • Callback onPoseChange dari pengubah Movable telah dihapus. Sebagai gantinya, gunakan onMove.
  • SubspaceModifiers tidak akan lagi menerapkan efeknya jika dilepas atau sedang dilepas.
  • SpatialRow API yang ada telah dibagi menjadi SpatialRow dan SpatialCurvedRow. Jika sebelumnya menggunakan parameter curveRadius SpatialRow, gunakan SpatialCurvedRow sekarang yang menawarkan perilaku yang sama.
  • MainPanel dan ActivityPanel tidak lagi memiliki kolom judul saat dijalankan pada image sistem yang sama-sama baru.
  • Pengubah alfa dan skala kini dapat ditumpuk dan akan mengalikan nilainya untuk nilai alfa atau skala akhir yang diterapkan.
  • Callback onPoseChange dari pengubah Movable telah dioptimalkan untuk melakukan gerakan pose yang lebih lancar.
  • Pengubah yang dapat dipindahkan dan diubah ukurannya kini akan melakukan callback-nya di thread utama untuk memastikan bahwa perubahan status akan memicu rekomposisi.
  • Menambahkan pengamatan status ke fase tata letak dan pengukuran untuk memastikan bahwa perubahan status di SubspaceLayout akan memicu tata letak ulang.
  • Update rantai pengubah yang dioptimalkan untuk menggunakan kembali pengubah yang ada dengan lebih baik.

Perbaikan Bug

  • Menghentikan scrim saat SpatialDialog ditampilkan. (Ic4594)
  • Permintaan tata letak ulang yang dibuat saat node pengubah dilepas kini akan diabaikan.
  • Menghapus fase tata ulang yang dipicu oleh pengubah Movable dan Resizable.
  • Memperbaiki error pada composable MainPanel() yang terjadi saat salah satu dimensi disetel ke nol, baik secara langsung maupun selama penghitungan tata letak, misalnya, penghitungan SpatialRow/SpatialColumn. Panel akan disembunyikan. Perhatikan bahwa perbaikan ini secara khusus mengatasi error saat fase tata letak; pengubahan ukuran panel menjadi nol melalui interaksi pengguna akan ditangani secara terpisah. Panel tersembunyi tidak memiliki afordans UI.
  • Memperbaiki masalah terkait maintainAspectRatio dari pengubah yang dapat diubah ukurannya. Rasio aspek harus dipertahankan sekarang.
  • Memperbaiki masalah dengan Subruang bertingkat yang akan diposisikan secara salah untuk satu frame.
  • Memperbaiki masalah saat sudut bulat terkadang tidak diterapkan saat seharusnya diterapkan.
  • NestedSubspaces tidak akan lagi muncul untuk satu frame di lokasi yang salah.

Versi 1.0.0-alpha03

26 Februari 2025

androidx.xr.compose:compose:1.0.0-alpha03 dan androidx.xr.compose:compose-testing:1.0.0-alpha03 dirilis tanpa perubahan penting sejak versi alfa terakhir. Versi 1.0.0-alpha03 berisi commit ini

Versi 1.0.0-alpha02

12 Februari 2025

androidx.xr.compose:compose:1.0.0-alpha02 dan androidx.xr.compose:compose-testing:1.0.0-alpha02 dirilis. Versi 1.0.0-alpha02 berisi commit ini.

Fitur Baru

  • Panel Aktivitas kini dapat mengaburkan kontennya saat Dialog Spasial diaktifkan.
  • API Orbiter kini dapat digunakan dalam konteks SubspaceComposable dan akan melampirkan Orbiter ke induk composable berbasis SubspaceLayout terdekat.
  • Memperkenalkan LayoutCoordinatesAwareModifierNode untuk mengizinkan pengubah berbasis penempatan kustom.
  • Menambahkan metode siklus proses pelekatan/pelepasan ke SubspaceModifier.Node.
  • Menambahkan scaleWithDistance ke pengubah yang dapat dipindahkan. Jika scaleWithDistance diaktifkan, elemen subruang yang dipindahkan akan bertambah besar atau kecil. Skala eksplisit yang dimilikinya sebelum pergerakan juga akan dipertahankan.

Perubahan API

  • SessionCallbackProvider dihapus dan digantikan dengan SpatialCapabilities.

Perubahan lainnya

  • Mengurangi minSDK menjadi 24. Semua Jetpack XR API terus memerlukan API 34 saat runtime.
  • Konstruktor Orbiter EdgeOffset.inner, EdgeOffset.outer, dan EdgeOffset.overlap tidak lagi menjadi metode @Composable, sehingga dapat digunakan dalam konteks non-composable.
  • Perbarui Tingkat Ketinggian Spasial agar sesuai dengan spesifikasi UX terbaru.
  • Terapkan antarmuka SubspaceSemanticsInfo ke MeasurableLayout.
  • Mengganti nama SubspaceModifierElement menjadi SubspaceModifierNodeElement.

Perbaikan bug

  • Perbaikan untuk menstabilkan pemesanan SubspaceModifier. SubspaceModifier akan berperilaku lebih andal. Pengubah offset, putar, skala, dapat dipindahkan, dan dapat diubah ukurannya kini dapat digunakan dalam urutan apa pun.

Versi 1.0.0-alpha01

12 Desember 2024

androidx.xr.compose:compose-*1.0.0-alpha01 dirilis.

Fitur Rilis Awal

  • Rilis developer awal Jetpack Compose untuk XR. Gunakan konsep Compose yang sudah dikenal seperti baris dan kolom untuk membuat tata letak UI spasial di XR, baik Anda mem-porting aplikasi 2D yang ada ke XR atau membuat aplikasi XR baru dari awal. Library ini menyediakan composable subruang dan spasial: seperti panel spasial dan pengorbit, yang memungkinkan Anda menempatkan UI berbasis Compose 2D atau Views yang ada dalam tata letak spasial. Bagian ini memperkenalkan composable Volume subspace, yang memungkinkan Anda menempatkan entity SceneCore, seperti model 3D, relatif terhadap UI Anda. Pelajari lebih lanjut di panduan developer ini:

    • Subspace: Composable ini dapat ditempatkan di mana saja dalam hierarki UI aplikasi Anda, sehingga Anda dapat mempertahankan tata letak untuk UI 2D dan spasial tanpa kehilangan konteks antar-file. Hal ini mempermudah berbagi hal-hal seperti arsitektur aplikasi yang ada antara XR dan faktor bentuk lainnya tanpa perlu mengangkat status melalui seluruh hierarki UI atau mendesain ulang aplikasi.

    • SpatialPanel: Panel spasial adalah composable subruang yang memungkinkan Anda menampilkan konten aplikasi–misalnya, Anda dapat menampilkan pemutaran video, gambar diam, atau konten lainnya di panel spasial.

    • Orbiter: Orbiter adalah komponen UI spasial. Panel ini dirancang untuk dilampirkan ke panel spasial yang sesuai, dan berisi item tindakan kontekstual dan navigasi yang terkait dengan panel spasial tersebut. Misalnya, jika Anda telah membuat panel spasial untuk menampilkan konten video, Anda dapat menambahkan kontrol pemutaran video di dalam pengorbit.

    • Volume: Tempatkan entity SceneCore, seperti model 3D, relatif terhadap UI Anda.

  • Tata Letak Spasial: Anda dapat membuat beberapa panel spasial dan menempatkannya dalam Tata Letak Spasial menggunakan SpatialRow, SpatialColumn, SpatialBox, dan SpatialLayoutSpacer. Gunakan SubspaceModifiers untuk menyesuaikan tata letak Anda.

  • Komponen UI spasial: Elemen ini dapat digunakan kembali di UI 2D Anda, dan atribut spasialnya hanya akan terlihat saat kemampuan spasial diaktifkan.

    • SpatialDialog: Panel akan sedikit didorong kembali dalam kedalaman z untuk menampilkan dialog yang lebih tinggi.
    • SpatialPopUp: Panel akan sedikit mundur dalam kedalaman z untuk menampilkan pop-up yang lebih tinggi
    • SpatialElevation: SpatialElevationLevel dapat ditetapkan untuk menambahkan elevasi.

  • SpatialCapabilities: Kemampuan spasial dapat berubah saat pengguna berinteraksi dengan aplikasi atau sistem Anda, atau bahkan dapat diubah oleh aplikasi Anda sendiri—misalnya, berpindah ke Ruang Utama atau Ruang Penuh. Untuk menghindari masalah, aplikasi Anda perlu memeriksa LocalSpatialCapabilities.current untuk menentukan API mana yang didukung di lingkungan saat ini. isSpatialUiEnabled: Elemen UI spasial (misalnya SpatialPanel) isContent3dEnabled: Objek 3D isAppEnvironmentEnabled: Lingkungan isPassthroughControlEnabled: Apakah aplikasi dapat mengontrol status penerusan atau tidak isSpatialAudioEnabled: Audio spasial

Masalah Umum

  • Saat ini, minSDK 30 diperlukan untuk menggunakan Jetpack Compose untuk XR. Sebagai solusi sementara, Anda dapat menambahkan entri manifes <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> berikut agar dapat membangun dan menjalankan dengan minSDK 23.
  • Aplikasi Jetpack XR saat ini memerlukan permintaan izin android.permission.SCENE_UNDERSTANDING di AndroidManifest.
  • Saat aplikasi diluncurkan langsung ke Ruang Penuh menggunakan properti PROPERTY_XR_ACTIVITY_START_MODE dalam manifesnya, Aktivitas/Aplikasi awalnya dibuka di Ruang Utama sebelum bertransisi ke Ruang Penuh.
  • glTF di Volume Composables mungkin awalnya berkedip di lokasi yang salah.
  • Menggunakan SpatialDialog di panel yang telah dipindahkan secara signifikan akan mendorong konten ke arah yang salah.