Memahami pengubah subruang

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Headset XR
Kacamata XR Berkabel
Mempelajari jenis perangkat XR →

SubspaceModifier mirip dengan pengubah Compose untuk composable dalam Subspace. SubspaceModifier memungkinkan Anda memanipulasi composable dalam ruang 3D, membantu Anda memosisikan, memutar, dan menambahkan perilaku ke node tata letak 3D.

Tata Letak

Secara default, Subspace dibatasi oleh ruang yang direkomendasikan untuk menampilkan aplikasi. Batas ini digunakan saat mengukur tata letak komponen subruang Anda, mirip dengan batas dalam tata letak Compose 2D.

Batas pengisian

Pengubah fillMaxSize, fillMaxWidth, fillMaxHeight, dan fillMaxDepth membuat konten mengisi (sebagian) batas induknya. Penggunaan pengubah pengisian membantu tata letak aplikasi Anda menampilkan konten yang tidak bergantung pada karakteristik tampilan perangkat XR.

Menetapkan ukuran dan ukuran yang diperlukan

Pengubah size, width, height, dan depth mendeklarasikan ukuran konten yang diinginkan. Untuk menyatakan ukuran persis konten, gunakan requiredSize, requiredWidth, requiredHeight, dan requiredDepth. Unit ini harus ditentukan dalam dp; untuk mengonversi dari meter ke dp, gunakan Meter.toDp().

Memosisikan composable

offset

Pengubah offset memindahkan composable dalam ruang 3D di sepanjang sumbu x, y, dan z. Unit ini harus ditentukan dalam dp; untuk mengonversi dari meter ke dp, gunakan Meter.toDp().

rotate

Pengubah rotate memutar composable tertentu di ruang. Anda dapat menentukan arah dan jumlah rotasi dengan berbagai cara:

  • Menggunakan pitch, yaw, dan roll, yang menentukan rotasi di sekitar sumbu x, y, dan z,
  • Menggunakan axisAngle, yang merupakan Vector3 yang merepresentasikan sumbu rotasi, dan jumlah derajat yang harus diputar,
  • Menggunakan Quaternion yang merepresentasikan rotasi.

rotateToLookAtUser

Pengubah rotateToLookAtUser terus memutar konten sehingga selalu menghadap ke pengguna. Anda juga dapat menggunakan pengubah ini untuk mencapai efek "papan iklan" saat konten berputar menghadap pengguna pada sumbu Y sambil tetap tegak dan sejajar dengan gravitasi. Untuk melakukannya, gabungkan pengubah rotateToLookAtUser dengan pengubah gravityAligned.

Memindahkan dan mengubah ukuran composable

Izinkan pengguna memanipulasi posisi dan ukuran objek secara langsung dalam ruang 3D.

Memindahkan elemen

Jika pengubah movable ada dan diaktifkan, kontrol UI yang dapat ditarik akan ditampilkan, sehingga pengguna dapat memindahkan elemen dalam ruang 3D. Anda dapat menerapkan pengubah movable ke seluruh Subspace, komponen tata letak spasial (seperti SpatialRow dan SpatialColumn), serta komponen individual (seperti SpatialPanel dan SpatialGltfModel).

Perilaku spesifik dari gerakan ini ditentukan oleh movePolicy yang disediakan:

  • MovePolicy.Default (atau MovePolicy.system()): Sistem menangani pergerakan sepenuhnya dan secara otomatis menghitung serta menerapkan pose dan skala baru berdasarkan input pengguna.
  • MovePolicy.custom(): Sistem menghitung target Pose berdasarkan input, tetapi tidak otomatis menerapkannya ke elemen terkait. Hal ini berguna untuk membatasi gerakan atau membuat gerakan kustom di aplikasi Anda.
  • MovePolicy.anchor(): Memungkinkan pengguna menempelkan dan menambatkan elemen yang dapat dipindahkan ke bidang dunia nyata yang terdeteksi.

Composable anchor

Agar dapat menambatkan composable subruang yang dapat dipindahkan ke permukaan dunia nyata, teruskan MovePolicy.anchor() ke pengubah movable. Kebijakan ini memungkinkan pengguna menempelkan elemen (seperti SpatialPanel dan SpatialGltfModel) ke permukaan fisik seperti meja, dinding, atau lantai.

Anda dapat memfilter bidang terdeteksi yang dapat dipasangi elemen menggunakan parameter berikut (jika dibiarkan kosong, elemen dapat dipasangi ke bidang terdeteksi mana pun):

  • anchorPlaneOrientations: Serangkaian nilai PlaneOrientation (Horizontal, Vertical, atau Any).
  • anchorPlaneSemantics: Serangkaian nilai PlaneSemantic (Wall, Floor, Ceiling, Table, atau Any).

Mengubah ukuran elemen

Jika pengubah resizable() ada dan diaktifkan, kontrol UI akan ditampilkan yang memungkinkan pengguna mengubah ukuran elemen di ruang 3D. Perilaku khusus pengubahan ukuran ditentukan oleh resizePolicy yang disediakan:

  • ResizePolicy.default(): Sistem akan otomatis menangani gestur pengubahan ukuran dan menerapkan dimensi baru ke konten.
  • ResizePolicy.custom(): Sistem menyediakan SpatialResizeEvent dan tidak otomatis menerapkan hasil pengubahan ukuran ke elemen terkait.

Mengubah tampilan komponen

alpha

Pengubah alpha menetapkan opasitas elemen dan turunannya, dengan 0f mewakili sepenuhnya transparan dan 1.0f mewakili sepenuhnya buram.

scale

Pengubah scale menskalakan konten composable di sepanjang sumbu horizontal, vertikal, dan kedalaman.

Pengujian dan aksesibilitas

semantics

Pengubah semantics menambahkan semantik ke node tata letak, untuk digunakan dalam pengujian dan aksesibilitas. Lihat Semantik di Jetpack Compose dan SemanticsModifier.

testTag

Pengubah testTag adalah singkatan dari SemanticsPropertyReceiver.testTag, yang memungkinkan framework pengujian menemukan elemen dalam pengujian.