Jetpack Compose per XR

Jetpack Compose per XR

Guida dell'utente  Esempio di codice  Codelab

Riferimento 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

Crea in modo dichiarativo layout dell'interfaccia utente spaziale che sfruttano le funzionalità spaziali di Android XR.

Ultimo aggiornamento	Release stabile	Candidato per la release	Versione beta	Versione alpha
7 maggio 2025	-	-	-	1.0.0-alpha04

Dichiarazione delle dipendenze

Per aggiungere una dipendenza a XR compose, devi aggiungere il repository Maven di Google al tuo progetto. Per ulteriori informazioni, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli elementi necessari nel file build.gradle per la tua app o il tuo modulo:

Alla modaKotlin Altro

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

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

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

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

Per ulteriori informazioni sulle dipendenze, consulta Aggiungere dipendenze di compilazione.

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa raccolta. Prima di crearne uno nuovo, dai un'occhiata ai problemi esistenti in questa raccolta. Puoi aggiungere il tuo voto a un problema esistente facendo clic sul pulsante a forma di stella.

Creare un nuovo problema

Per ulteriori informazioni, consulta la documentazione del Tracker dei problemi.

Versione 1.0

Versione 1.0.0-alpha04

7 maggio 2025

androidx.xr.compose:compose:1.0.0-alpha04 e androidx.xr.compose:compose-testing:1.0.0-alpha04 vengono rilasciati. La versione 1.0.0-alpha04 contiene questi commit.

Nota: per utilizzare questa versione della libreria è necessario Android Emulator 35.6.7 o versioni successive.

Nuove funzionalità

• È stata aggiunta l'interfaccia CompositionLocalConsumerSubspaceModifierNode per consentire ai tipi SubspaceModifier personalizzati di accedere ai valori locali della composizione.
• È stata aggiunta una nuova API SpatialPanel che segue lo stile di implementazione di Compose AndroidView e ritira la precedente ViewBased SpatialPanel.
• È stato aggiunto l'oggetto complementare VolumeConstraints.Unbounded che rappresenta vincoli illimitati.
• È stato aggiunto SubspaceModifier.onPointSourceParams per consentire un'origine audio spazializzata.
• È stato aggiunto un ApplicationSubspace pubblico che offre VolumeConstraints facoltativi per definire un'area 3D in cui l'app può visualizzare contenuti spaziali. Per impostazione predefinita, se non vengono specificati vincoli, lo spazio sottostante sarà delimitato dall'attuale campo visivo di SpatialUser in larghezza e altezza. Gli utenti possono fornire vincoli da utilizzare se non è possibile determinare il campo visivo. In caso contrario, vengono utilizzati i valori predefiniti di larghezza e altezza del campo visivo.
• È stato aggiunto SpatialExternalSurface, che può essere utilizzato per il rendering di contenuti stereoscopici. SpatialExternalSurface è personalizzabile con modificatori (tranne alpha) e un effetto sfumatura dei bordi.
• È stato aggiunto un nuovo modificatore di sottospazio pointerHoverIcon che consente agli utenti di impostare l'icona per il cursore spaziale.

Modifiche all'API

• È stata rimossa la limitazione RequiresApi(34) su tutti i pacchetti Jetpack XR. Questa limitazione era ridondante perché Jetpack XR è attualmente disponibile solo sui dispositivi con livello API 34 e versioni successive. (Iae0f8)
• I progetti rilasciati con Kotlin 2.0 richiedono KGP 2.0.0 o versioni successive per essere utilizzati. (Idb6b5)
• La gestione del pulsante Indietro ora funziona nei riquadri spaziali senza attività incorporate. Affinché la gestione del pulsante Indietro funzioni, devi specificare android:enableOnBackInvokedCallback="true" nel file manifest Android.
• La gestione a ritroso ora funziona nelle conversazioni spaziali. Affinché il backhandling funzioni, devi specificare android:enableOnBackInvokedCallback="true" nel file manifest Android.
• Ora i SpatialPanel basati su composizione e visualizzazione possono adattarsi alle dimensioni dei contenuti.
• Ora gli sviluppatori possono impostare i propri valori SpatialElevationLevel personalizzati e non sono limitati ai livelli predefiniti.
• Ora il livello di elevazione dell'orbiter può essere personalizzato tramite il parametro elevation.
• Per impostazione predefinita, lo spazio sottostante può essere delimitato dal campo visivo di SpatialUser in larghezza e altezza. Se non è possibile determinare il campo visivo, vengono utilizzati i valori predefiniti di larghezza e altezza del campo visivo.
• Sono stati aggiunti nuovi callback onMoveStart e onMoveEnd al modificatore Movable. I callback onMoveStart e onMoveEnd vengono chiamati quando l'utente inizia e termina lo spostamento di un sottospazio componibile con il modificatore mobile.
• Il parametro name è stato rimosso dalle API spaziali come SpatialRow e SpatialPanel. Per il debug delle strutture di composizione spaziale, utilizza invece SubspaceModifier.testTag.
• È stata rimossa un'overload non supportata di SpatialPopup che ha solo spatialElevationLevel e content. Utilizza l'interfaccia che supporta onDimissRequest.
• Il callback onPoseChange dal modificatore Movable è stato rimosso. Utilizza invece onMove.
• SubspaceModifiers non applicherà più i propri effetti se è scollegato o è in corso lo scollegamento.
• L'API SpatialRow esistente è stata suddivisa in SpatialRow e SpatialCurvedRow. Se in precedenza utilizzavi il parametro curveRadius di SpatialRow, ora utilizza SpatialCurvedRow, che offre lo stesso comportamento.
• MainPanel e ActivityPanel non hanno più barre dei titoli quando vengono eseguiti su un'immagine di sistema altrettanto recente.
• I modificatori di alfa e scala ora sono impilabili e moltiplicano i loro valori per il valore alfa o di scala applicato finale.
• Il callout onPoseChange del modificatore Movable è stato ottimizzato per eseguire un movimento più fluido delle pose.
• Ora i modificatori spostabili e ridimensionabili eseguiranno i relativi callback sul thread principale per garantire che le modifiche dello stato attiveranno la ricompozione.
• È stata aggiunta l'osservazione dello stato alle fasi di layout e misura per garantire che le modifiche dello stato in SubspaceLayout attiveranno il nuovo layout.
• Aggiornamenti della catena di modificatori ottimizzati per riutilizzare meglio i modificatori esistenti.

Correzioni di bug

• La scrim è stata interrotta quando viene visualizzato un SpatialDialog. (Ic4594)
• Le richieste di nuovo layout effettuate quando i nodi modificatori sono scollegati verranno ora ignorate.
• Sono state rimosse le fasi di riallineamento attivate dai modificatori Spostabile e Ridimensionabile.
• È stato risolto un arresto anomalo nel composable MainPanel() che si verificava quando una delle dimensioni era impostata su zero, direttamente o durante un calcolo del layout, ad esempio un calcolo di SpatialRow/SpatialColumn. Il riquadro verrà invece nascosto. Tieni presente che questa correzione risolve in modo specifico i crash durante la fase di layout; la modifica delle dimensioni del riquadro in modo che sia pari a zero tramite l'interazione dell'utente verrà gestita separatamente. Il riquadro nascosto non offre funzionalità di UI.
• È stato risolto il problema relativo a maintainAspectRatio del modificatore ridimensionabile. Le proporzioni dovrebbero essere mantenute.
• È stato risolto un problema relativo agli spazi sottoinsiemi nidificati, che non venivano posizionati correttamente per un singolo frame.
• È stato risolto il problema per cui a volte i bordi arrotondati non venivano applicati quando dovevano.
• NestedSubspaces non verrà più visualizzato per un fotogramma nella posizione sbagliata.

Versione 1.0.0-alpha03

26 febbraio 2025

androidx.xr.compose:compose:1.0.0-alpha03 e androidx.xr.compose:compose-testing:1.0.0-alpha03 vengono rilasciati senza modifiche significative rispetto all'ultima versione alpha. La versione 1.0.0-alpha03 contiene questi commit

Versione 1.0.0-alpha02

12 febbraio 2025

androidx.xr.compose:compose:1.0.0-alpha02 e androidx.xr.compose:compose-testing:1.0.0-alpha02 vengono rilasciati. La versione 1.0.0-alpha02 contiene questi commit.

Nuove funzionalità

• Ora il riquadro delle attività può oscurare i contenuti quando è attivata una finestra di dialogo spaziale.
• L'API Orbiter è ora utilizzabile nei contesti SubspaceComposable e collegherà gli Orbiter al relativo elemento principale composable basato su SubspaceLayout più vicino.
• È stato introdotto LayoutCoordinatesAwareModifierNode per consentire modificatori basati sul posizionamento personalizzato.
• Sono stati aggiunti metodi del ciclo di vita di attacco/scollegamento a SubspaceModifier.Node.
• È stato aggiunto scaleWithDistance al modificatore mobile. Quando scaleWithDistance è attivato, l'elemento sottospazio spostato aumenta o diminuisce. Mantiene inoltre qualsiasi scala esplicita che aveva prima del movimento.

Modifiche all'API

• SessionCallbackProvider è stato rimosso in favore di SpatialCapabilities.

Altre modifiche

• Ridotto da minSDK a 24. Tutte le API Jetpack XR continuano a richiedere l'API 34 in fase di runtime.
• I costruttori Orbiter EdgeOffset.inner, EdgeOffset.outer e EdgeOffset.overlap non sono più metodi @Composable, il che consente di utilizzarli in contesti non componibili.
• Aggiorna i livelli di elevazione spaziale in modo che corrispondano alle ultime specifiche UX.
• Implementa l'interfaccia SubspaceSemanticsInfo in MeasurableLayout.
• SubspaceModifierElement rinominato in SubspaceModifierNodeElement.

Correzioni di bug

• Correzioni per stabilizzare l'ordinamento SubspaceModifier. SubspaceModifier dovrebbe comportarsi in modo più affidabile. Ora i modificatori offset, ruota, scala, spostabile e ridimensionabile dovrebbero essere utilizzabili in qualsiasi ordine.

Versione 1.0.0-alpha01

12 dicembre 2024

androidx.xr.compose:compose-*1.0.0-alpha01 viene rilasciato.

Funzionalità della versione iniziale

• Release iniziale per sviluppatori di Jetpack Compose per XR. Utilizza concetti di Compose familiari, come righe e colonne, per creare layout dell'interfaccia utente spaziale in XR, indipendentemente dal fatto che tu stia eseguendo il porting di un'app 2D esistente in XR o creando una nuova app XR da zero. Questa libreria fornisce composibili nello spazio e nello spazio sottostante, ad esempio pannelli e orbiter spaziali, che ti consentono di posizionare l'interfaccia utente 2D esistente basata su Compose o Views in un layout spaziale. Viene introdotto il composable sottospazio Volume, che consente di posizionare entità SceneCore, come i modelli 3D, rispetto all'interfaccia utente. Scopri di più in questa guida per gli sviluppatori:

  • 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'elevazione dello stato nell'intera struttura dell'interfaccia utente o ristrutturare l'app.

  • SpatialPanel: un riquadro spaziale è un componente componibile sottospaziale che ti consente di visualizzare i contenuti dell'app. Ad esempio, in un riquadro spaziale puoi visualizzare la riproduzione di video, immagini fisse o qualsiasi altro contenuto.

  • Orbiter: un orbiter è un componente dell'interfaccia utente spaziale. È progettato per essere collegato a un riquadro spaziale corrispondente e contiene attività di navigazione e contestuali correlate a quel riquadro spaziale. Ad esempio, se hai creato un riquadro spaziale per visualizzare contenuti video, puoi aggiungere i controlli di riproduzione video all'interno di un orbiter.

  • Volume: posiziona le entità SceneCore, ad esempio i modelli 3D, rispetto all'interfaccia utente.

• Layout spaziale: puoi creare più riquadri spaziali e posizionarli all'interno di un layout spaziale utilizzando SpatialRow, SpatialColumn, SpatialBox e SpatialLayoutSpacer. Utilizza i SubspaceModifier per personalizzare il layout.

• Componenti dell'interfaccia utente spaziale: questi elementi possono essere riutilizzati nell'interfaccia utente 2D e i relativi attributi spaziali saranno visibili solo quando le funzionalità spaziali sono attivate.

  • SpatialDialog: il riquadro si spingerà leggermente indietro in profondità z per visualizzare una finestra di dialogo in primo piano.
  • SpatialPopUp: il riquadro si spingerà leggermente indietro in Z-depth per visualizzare un popup rialzato
  • SpatialElevation: SpatialElevationLevel può essere impostato per aggiungere l'elevazione.

• SpatialCapabilities: le funzionalità spaziali possono cambiare man mano che gli utenti interagiscono con la tua app o con il sistema oppure possono essere modificate anche dalla tua app stessa, ad esempio passando allo spazio della casa o allo spazio completo. Per evitare problemi, l'app deve verificare la presenza di LocalSpatialCapabilities.current per determinare quali API sono supportate nell'ambiente corrente. isSpatialUiEnabled: elementi dell'interfaccia utente spaziale (ad es. SpatialPanel) isContent3dEnabled: oggetti 3D isAppEnvironmentEnabled: l'ambiente isPassthroughControlEnabled: indica se l'applicazione può controllare o meno lo stato di passthrough isSpatialAudioEnabled: audio spaziale

Problemi noti

• Attualmente è necessaria una versione minima dell'SDK pari a 30 per utilizzare Jetpack Compose per XR. Come soluzione alternativa, puoi aggiungere la seguente voce manifest <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> per poter eseguire la compilazione e l'esecuzione con un minSDK di 23.
• Al momento le app Jetpack XR richiedono la richiesta dell'autorizzazione android.permission.SCENE_UNDERSTANDING in AndroidManifest.
• Quando un'app viene avviata direttamente nello spazio intero utilizzando la proprietà PROPERTY_XR_ACTIVITY_START_MODE nel file manifest, le attività/app vengono inizialmente aperte nello spazio Home prima di passare allo spazio intero.
• I file glTF nei composabili di volume potrebbero inizialmente tremolare nella posizione sbagliata.
• L'utilizzo di un riquadro SpatialDialog in un riquadro spostato in modo significativo spingerà i contenuti nella direzione sbagliata.