Con Jetpack Compose per XR, puoi creare in modo dichiarativo l'interfaccia utente e il layout spaziali utilizzando concetti di Compose già noti, come righe e colonne. In questo modo puoi estendere la tua interfaccia utente Android esistente nello spazio 3D o creare applicazioni 3D immersive completamente nuove.
Se stai spazializzando un'app basata su Android Views esistente, hai a disposizione diverse opzioni di sviluppo. Puoi utilizzare le API di interoperabilità, Compose e le visualizzazioni insieme o lavorare direttamente con la libreria SceneCore. Per ulteriori dettagli, consulta la nostra guida all'utilizzo delle visualizzazioni.
Informazioni su sottospazi e componenti spazializzati
Quando scrivi la tua app per Android XR, è importante comprendere i concetti di spazio sottostante e componenti spazializzati.
Informazioni sullo spazio sottostante
Quando sviluppi per Android XR, devi aggiungere un sottospazio all'app o al layout. Un sottospazio è una partizione dello spazio 3D all'interno dell'app in cui puoi collocare contenuti 3D, creare layout 3D e aggiungere profondità a contenuti altrimenti 2D. Un subspazio viene visualizzato solo quando la spazializzazione è attivata. In Home Space o su dispositivi non XR, qualsiasi codice all'interno di questo sottospazio viene ignorato.
Esistono due modi per creare un sottospazio:
setSubspaceContent(): questa funzione crea un sottospazio a livello di app. Questo metodo può essere chiamato nell'attività principale nello stesso modo in cui utilizzisetContent(). Uno spazio sottospaziale a livello di app è illimitato in altezza, larghezza e profondità, fornendo essenzialmente un'area di lavoro infinita per i contenuti spaziali.Subspace: questo composable può essere posizionato in qualsiasi punto della gerarchia dell'interfaccia utente dell'app, consentendoti di mantenere i layout per l'interfaccia utente 2D e spaziale senza perdere il contesto tra i file. In questo modo è più facile condividere elementi come l'architettura dell'app esistente tra XR e altri fattori di forma senza dover eseguire l'hoisting dello stato nell'intera struttura dell'interfaccia utente o ristrutturare l'app.
Per ulteriori informazioni, vedi Aggiungere uno spazio secondario all'app.
Informazioni sui componenti spazializzati
Composabili in sottospazio: questi componenti possono essere visualizzati solo in un sottospazio.
Devono essere racchiusi tra Subspace o setSubspaceContent prima di essere collocati in un layout 2D. Un SubspaceModifier ti consente di aggiungere attributi come profondità, offset e posizionamento ai composabili sottospazio.
Gli altri componenti spazializzati non richiedono di essere chiamati all'interno di un sottospazio. Sono costituiti da elementi 2D convenzionali racchiusi in un contenitore spaziale. Questi elementi possono essere utilizzati all'interno di layout 2D o 3D se definiti per entrambi. Se la spazializzazione non è attivata, le relative funzionalità spazializzate verranno ignorate e verrà eseguito il fallback alle relative controparti 2D.
Creare un riquadro spaziale
Un SpatialPanel è un componente componibile sottospaziale che ti consente di visualizzare i contenuti dell'app. Ad esempio, puoi visualizzare la riproduzione di video, immagini fisse o qualsiasi altro contenuto in un riquadro spaziale.
Puoi utilizzare SubspaceModifier per modificare le dimensioni, il comportamento e il posizionamento del riquadro spaziale, come mostrato nell'esempio seguente.
Subspace {
SpatialPanel(
SubspaceModifier
.height(824.dp)
.width(1400.dp)
.movable()
.resizable()
) {
SpatialPanelContent()
}
}
// 2D content placed within the spatial panel
@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
)
}
}
Punti chiave del codice
- Poiché le API
SpatialPanelsono composibili in sottospazio, devi chiamarle all'interno diSubspaceosetSubspaceContent. Se li chiami al di fuori di un sottospazio, viene generata un'eccezione. - Consenti all'utente di ridimensionare o spostare il riquadro aggiungendo i modificatori
movableoresizable. - Per informazioni dettagliate su dimensioni e posizionamento, consulta le nostre linee guida per la progettazione dei riquadri spaziali. Per ulteriori dettagli sull'implementazione del codice, consulta la nostra documentazione di riferimento.
Creare un orbiter
Un orbiter è un componente dell'interfaccia utente spaziale. È progettato per essere collegato a un pannello spaziale, a un layout o a un'altra entità corrispondente. Un orbiter solitamente contiene attività di navigazione e contestuali correlate all'entità a cui è ancorato. Ad esempio, se hai creato un riquadro spaziale per visualizzare contenuti video, puoi aggiungere i controlli di riproduzione video all'interno di un orbiter.
Come mostrato nell'esempio seguente, chiama un orbiter all'interno del layout 2D in un
SpatialPanel per racchiudere i controlli utente come la navigazione. In questo modo, li estrae
dal layout 2D e li collega al riquadro spaziale in base alla tua
configurazione.
setContent {
Subspace {
SpatialPanel(
SubspaceModifier
.height(824.dp)
.width(1400.dp)
.movable()
.resizable()
) {
SpatialPanelContent()
OrbiterExample()
}
}
}
//2D content inside Orbiter
@Composable
fun OrbiterExample() {
Orbiter(
position = OrbiterEdge.Bottom,
offset = 96.dp,
alignment = Alignment.CenterHorizontally
) {
Surface(Modifier.clip(CircleShape)) {
Row(
Modifier
.background(color = Color.Black)
.height(100.dp)
.width(600.dp),
horizontalArrangement = Arrangement.Center,
verticalAlignment = Alignment.CenterVertically
) {
Text(
text = "Orbiter",
color = Color.White,
fontSize = 50.sp
)
}
}
}
}
Punti chiave del codice
- Poiché gli orbiter sono componenti dell'interfaccia utente spaziale, il codice può essere riutilizzato in layout 2D o 3D. In un layout 2D, l'app esegue il rendering solo dei contenuti all'interno dell'orbiter e ignora l'orbiter stesso.
- Consulta le nostre linee guida per la progettazione per saperne di più su come utilizzare e progettare gli orbiter.
Aggiungere più riquadri spaziali a un layout spaziale
Puoi creare più riquadri spaziali e posizionarli all'interno di un layout spaziale utilizzando SpatialRow, SpatialColumn,
SpatialBox e SpatialLayoutSpacer.
Il seguente esempio di codice mostra come eseguire questa operazione.
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
)
}
}
Punti chiave del codice
SpatialRow,SpatialColumn,SpatialBoxeSpatialLayoutSpacersono tutti composabili in sottospazio e devono essere inseriti in un sottospazio.- Utilizza
SubspaceModifierper personalizzare il layout. - Per i layout con più riquadri in una riga, consigliamo di impostare un raggio di curva di 825 dp utilizzando un
SubspaceModifierin modo che i riquadri circondino l'utente. Per maggiori dettagli, consulta le nostre linee guida per il design.
Utilizzare un volume per posizionare un oggetto 3D nel layout
Per posizionare un oggetto 3D nel layout, devi utilizzare un componibile sottospazio chiamato volume. Ecco un esempio di come fare.
Subspace {
SpatialPanel(
SubspaceModifier.height(1500.dp).width(1500.dp)
.resizable().movable()
) {
ObjectInAVolume(true)
Box(
Modifier.fillMaxSize(),
contentAlignment = Alignment.Center
) {
Text(
text = "Welcome",
fontSize = 50.sp,
)
}
}
}
}
@Composable
fun ObjectInAVolume(show3DObject: Boolean) {
val xrCoreSession = checkNotNull(LocalSession.current)
val scope = rememberCoroutineScope()
if (show3DObject) {
Subspace {
Volume(
modifier = SubspaceModifier
.offset(volumeXOffset, volumeYOffset, volumeZOffset) //
Relative position
.scale(1.2f) // Scale to 120% of the size
) { parent ->
scope.launch {
// Load your 3D Object here
}
}
}
}
}
Punti chiave del codice
- Consulta Aggiungere modelli 3D all'app per capire meglio come caricare contenuti 3D all'interno di un volume.
Aggiungere altri componenti dell'interfaccia utente spaziale
I componenti dell'interfaccia utente spaziale possono essere posizionati in qualsiasi punto della gerarchia dell'interfaccia utente dell'applicazione. Questi elementi possono essere riutilizzati nell'interfaccia utente 2D e i relativi attributi spaziali saranno visibili solo quando le funzionalità spaziali sono attivate. In questo modo puoi aggiungere un'elevazione a menu, finestre di dialogo e altri componenti senza dover scrivere il codice due volte. Consulta i seguenti esempi di UI spaziale per comprendere meglio come utilizzare questi elementi.
Componente UI |
Quando la spazializzazione è attivata |
In ambiente 2D |
|---|---|---|
|
Il riquadro si spingerà leggermente indietro in profondità Z per visualizzare una finestra di dialogo in primo piano |
Torna alla modalità 2D |
|
Il riquadro si spingerà leggermente indietro in profondità z per visualizzare un popup rialzato |
Torna a un |
|
|
Programmi senza elevazione spaziale. |
SpatialDialog
Questo è un esempio di finestra di dialogo che si apre dopo un breve ritardo. Quando viene utilizzato SpatialDialog, la finestra di dialogo viene visualizzata alla stessa profondità z del pannello spaziale, che viene spostato indietro di 125 dp quando la spazializzazione è attivata. SpatialDialog può essere utilizzato anche quando la spazializzazione non è attiva,
in questo caso SpatialDialog passa alla sua controparte 2D, Dialog.
@Composable
fun DelayedDialog() {
var showDialog by remember { mutableStateOf(false) }
LaunchedEffect(Unit) {
Handler(Looper.getMainLooper()).postDelayed({
showDialog = true
}, 3000)
}
if (showDialog) {
SpatialDialog (
onDismissRequest = { showDialog = false },
SpatialDialogProperties(
dismissOnBackPress = true)
){
Box(Modifier
.height(150.dp)
.width(150.dp)
) {
Button(onClick = { showDialog = false }) {
Text("OK")
}
}
}
}
}
Punti chiave del codice
- Questo è un esempio di
SpatialDialog. L'utilizzo diSpatialPopUpeSpatialElevationè molto simile. Per ulteriori dettagli, consulta il nostro riferimento all'API.
Creare pannelli e layout personalizzati
Per creare riquadri personalizzati non supportati da Compose for XR, puoi lavorare direttamente con PanelEntities e la scena utilizzando le API SceneCore.
Ancorare gli orbitanti a layout spaziali e altre entità
Puoi ancorare un orbiter a qualsiasi entità dichiarata in Compose. Ciò comporta la dichiarazione di un orbiter in un layout spaziale di elementi dell'interfaccia utente come SpatialRow, SpatialColumn o SpatialBox. L'orbiter si ancora all'entità principale più vicina al punto in cui l'hai dichiarata.
Il comportamento dell'orbiter è determinato dal punto in cui lo dichiari:
- In un layout 2D racchiuso in un
SpatialPanel(come mostrato in uno snippet di codice precedente), l'orbiter si ancora a questoSpatialPanel. - In un
Subspace, l'orbiter si ancora all'entità principale più vicina, ovvero al layout spaziale in cui è dichiarato.
L'esempio seguente mostra come ancorare un orbiter a una riga spaziale:
Subspace {
SpatialRow {
Orbiter(
position = OrbiterEdge.Top,
offset = EdgeOffset.inner(8.dp),
shape = SpatialRoundedCornerShape(size = CornerSize(50))
) {
Text(
"Hello World!",
style = MaterialTheme.typography.titleLarge,
modifier = Modifier
.background(Color.White)
.padding(16.dp)
)
}
SpatialPanel(
SubspaceModifier
.height(824.dp)
.width(1400.dp)
) {
Box(
modifier = Modifier
.background(Color.Red)
)
}
SpatialPanel(
SubspaceModifier
.height(824.dp)
.width(1400.dp)
) {
Box(
modifier = Modifier
.background(Color.Blue)
)
}
}
}
Punti chiave del codice
- Quando dichiari un orbiter al di fuori di un layout 2D, l'orbiter si ancora all'entità principale più vicina. In questo caso, l'orbiter si ancora alla parte superiore del
SpatialRowin cui è dichiarato. - A tutti i layout spaziali, come
SpatialRow,SpatialColumneSpatialBox, sono associate entità senza contenuti. Pertanto, un orbiter dichiarato in un layout spaziale si ancora a quel layout.
Vedi anche
- Aggiungere modelli 3D all'app
- Sviluppare l'interfaccia utente per le app basate su View per Android
- Implementare Material Design per XR