Jetpack Compose per XR

Dichiarazione di dipendenze

Per aggiungere una dipendenza da XR Compose, devi aggiungere il repository Maven di Google al tuo progetto. Per saperne di più, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli artefatti che ti servono nel file build.gradle per la tua app o il tuo modulo:

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

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

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

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa libreria. Prima di crearne uno nuovo, dai un'occhiata ai problemi esistenti in questa libreria. 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 di Issue Tracker.

Versione 1.0

Versione 1.0.0-alpha05

30 luglio 2025

androidx.xr.compose:compose:1.0.0-alpha05 e androidx.xr.compose:compose-testing:1.0.0-alpha05 sono stati rilasciati. La versione 1.0.0-alpha05 contiene questi commit.

Nuove funzionalità

• È stata resa pubblica la classe di annotazione SubspaceComposable. (Ic2a34, b/399432430)
• Due nuovi composable SpatialExternalSurface che rappresentano sfere a 180 e 360 gradi. (I40ef2, b/391705799)
• Aggiunto SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147)
• È stata aggiunta l'API SceneCoreEntity per migliorare l'interoperabilità tra SceneCore e Compose for XR. (I50bb3, b/423020989)
• È stata fornita l'API GravityAlignedsubspace per supportare la funzionalità GravityAligned senza scalatura (I07359)

Modifiche alle API

• SpatialDialog() seguirà la configurazione della pressione di SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
• Aggiorna minimumPanelDimension a una nuova dimensione predefinita di Dimensions(0.1f, 0.1f, 0.1f) a causa della sua rappresentazione in metri. (Ib852a)
• Gli spazi secondari e gli Orbiter ora mantengono il loro stato interno nello spazio della casa e quando l'app è in background. In modalità Spazio della casa, Subspace configurerà comunque la scena in preparazione del passaggio alla modalità Spazio intero. (I40317, b/416037751)
• SpatialDialogs ora manterrà il proprio stato quando l'app è in background. (I6aa56)
• ApplicationSubspace ora erediterà la scala e la posizione consigliate dal sistema. (I4565f, b/418834194)
• È stato aggiunto un messaggio di errore migliore e l'errore viene attivato prima quando viene utilizzato un SubspaceComposable in un contesto non SubspaceComposable. (Iee2ae, b/416484684)
• Aggiornamento di ExperimentalSubspaceVolumeApi da Avviso a Errore perché gli avvisi vengono spesso trascurati quando si utilizzano in modo improprio le API componibili. (I427aa, b/424864286)
• Subspace e ApplicationSubspace ora sono vincolati da recommendedContentBoxInFullSpace. In precedenza era limitato dal campo visivo di SpatialUser. (I41015, b/423074142)
• Aggiorna SpatialElevation in modo che utilizzi la dimensione minima per non utilizzare più la dimensione hardcoded (I2dbe6, b/427785338)
• Aggiorna il modo in cui eseguiamo lo scrim di SpatialAcitivityPanel per aggiornarlo quando viene modificata una variabile chiave. (I0f64d, b/427999029)
• Rimuovi VolumeConstraints.Unbounded e imposta i valori predefiniti del vincolo sull'equivalente. (Ie24ec, b/407938414)
• SpatialFeatheringSize non è più pubblico (I1c15b, b/399432430)
• È stato rinominato Placeable XR in SubspacePlaceable per distinguerlo da Placeable di Composizione. (I74874)
• Rimozione delle impostazioni di Orbiter e aggiunta di shouldRenderInNonSpatial come nuovo parametro. Inoltre, rimuovendo la classe EdgeOffset e aggiungendo orbiterOffsetType come nuovo parametro per consolidare le funzioni Orbiter(). Oltre a rinominare OrbiterEdge in ContentEdge. (Iebf3d)
• Il nome Measurable è stato modificato in SubspaceMeasurable per distinguere il tipo dal tipo Measurable di Compose. (I9726c)
• Rinomina MeasureResult in SubspaceMeasureResult (I9f34d)
• È stata rimossa l'API setSubspaceContent a favore dell'utilizzo di setContent di Compose con un composable Subspace. (Ifff4c, b/421427391, b/421427391)
• MeasurePolicy è stato rinominato in SubspaceMeasurePolicy. (I37a9b, b/422553904)
• Trasforma SubspaceSemanticsInfo in un'interfaccia sigillata perché non potremo aggiungere membri senza i valori predefiniti. (I372f9, b/423704068)
• Documentazione di SpatialExternalSurface aggiornata, ContentSecurityLevel rinominato in SurfaceProtection (I3c460, b/420982808)
• È stato fornito un costruttore di overload per il modificatore mobile che consente l'ancoraggio. (Ic0c70)
• Aggiungi un altro fornitore di posizione per le descrizioni comando, in modo che gli sviluppatori possano controllare se la descrizione comando viene posizionata sopra, sotto, a sinistra o a destra dell'ancora. Aggiungi un'API che accetta una forma per i cursori, in modo da poter fornire forme più personalizzate. (Ie513c, b/374766087, b/418854637)
• CoreEntity rimosso come PublishedApi (Ifee05)

Correzioni di bug

• È stato risolto il problema per cui SpatialDialog lampeggiava durante il rendering. (Ife73c, b/401619909)
• È stato risolto il problema per cui SpatialDialog non poteva oscurare il riquadro Attività. (I8ca6c, b/367442109)
• Correzione della finestra di dialogo XR che non mostra alcuni contenuti (I17cd5, b/418062437)
• È stato risolto il problema a causa del quale SpatialPopup veniva chiuso quando si faceva clic all'interno del contenuto. (If262c, b/417245722)
• È stato risolto il problema per cui, quando si concatenava resizable().movable(), il riquadro spaziale non veniva ridimensionato correttamente alla nuova dimensione. (I02ee3, b/422264230)
• Correzione del problema di sovrapposizione di topBar con il menu in SpatialComposeVideoPlayer (Id33bc, b/427168167)
• Raggio angolo fisso non visualizzato (I975fe, b/428261830)

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 sono stati rilasciati. La versione 1.0.0-alpha04 contiene questi commit.

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 i 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ò eseguire il rendering dei contenuti spaziali. Per impostazione predefinita, se non vengono specificati vincoli, il sottospazio sarà delimitato dal campo visivo attuale della 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 del bordo.
• È stato aggiunto un nuovo modificatore pointerHoverIcon Subspace che consente agli utenti di impostare l'icona per il puntatore spaziale.

Modifiche alle API

• Rimossa la limitazione RequiresApi(34) su tutti i pacchetti Jetpack XR. Questa limitazione era ridondante in quanto Jetpack XR è attualmente disponibile solo sui dispositivi con livello API 34 o superiore. (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 funzionerà sui riquadri spaziali senza attività incorporate. Per il funzionamento della gestione del pulsante Indietro, devi specificare android:enableOnBackInvokedCallback="true" nel manifest Android.
• Ora la gestione del backhandling funziona sulle finestre di dialogo spaziali. Per il funzionamento della gestione del pulsante Indietro, devi specificare android:enableOnBackInvokedCallback="true" nel manifest Android.
• Le SpatialPanel basate sulla composizione e sulla visualizzazione ora possono dimensionarsi in base ai loro contenuti.
• Gli sviluppatori ora 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.
• Ora il sottospazio può essere delimitato dal campo visivo della SpatialUser in larghezza e altezza per impostazione predefinita. 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 elemento componibile dello spazio secondario con il modificatore spostabile.
• Il parametro name è stato rimosso dalle API spaziali come SpatialRow e SpatialPanel. Per il debug degli alberi di composizione spaziale, utilizza invece SubspaceModifier.testTag.
• È stata rimossa una funzione di overload non supportata di SpatialPopup che ha solo spatialElevationLevel e content. Utilizza l'interfaccia che supporta onDimissRequest.
• Il callback onPoseChange del modificatore mobile è stato rimosso. Utilizza invece onMove.
• SubspaceModifiers non applicherà più i suoi effetti se è scollegato o in fase di 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 del titolo se eseguiti su un'immagine di sistema recente.
• I modificatori alfa e di scala ora sono cumulabili e moltiplicano i loro valori per il valore alfa o di scala finale applicato.
• Il callback onPoseChange del modificatore Movable è stato ottimizzato per un movimento della posa più fluido.
• I modificatori mobili e ridimensionabili ora eseguiranno i callback sul thread principale per garantire che le modifiche dello stato attivino la ricomposizione.
• È stata aggiunta l'osservazione dello stato alle fasi di layout e misurazione per garantire che le modifiche dello stato in SubspaceLayout attivino il ricalcolo del layout.
• Aggiornamenti della catena di modificatori ottimizzata per riutilizzare meglio i modificatori esistenti.

Correzioni di bug

• Interrompe la visualizzazione della schermata quando viene mostrato un SpatialDialog. (Ic4594)
• Le richieste di riorganizzazione effettuate mentre i nodi modificatori sono scollegati verranno ora ignorate.
• Sono state rimosse le fasi di riorganizzazione attivate dai modificatori Spostabile e Ridimensionabile.
• È stato corretto 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 SpatialRow/SpatialColumn. Il pannello verrà invece nascosto. Tieni presente che questa correzione riguarda in modo specifico gli arresti anomali durante la fase di layout; il ridimensionamento del riquadro a zero tramite l'interazione dell'utente verrà gestito separatamente. Il pannello nascosto non dispone di funzionalità di accessibilità dell'interfaccia utente.
• È stato risolto il problema relativo a maintainAspectRatio del modificatore ridimensionabile. Le proporzioni dovrebbero essere mantenute.
• Risolto un problema relativo agli spazi secondari nidificati, che venivano posizionati in modo errato per un singolo fotogramma.
• È stato risolto il problema a causa del quale a volte gli angoli arrotondati non venivano applicati quando avrebbero dovuto.
• NestedSubspaces non verrà più visualizzato per un fotogramma nella posizione errata.

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 sono stati rilasciati. La versione 1.0.0-alpha02 contiene questi commit.

Nuove funzionalità

• Il riquadro Attività ora può oscurare i suoi contenuti quando viene attivato un dialogo spaziale.
• L'API Orbiter ora è utilizzabile nei contesti SubspaceComposable e collegherà gli orbiter al relativo elemento componibile principale basato su SubspaceLayout più vicino.
• È stato introdotto LayoutCoordinatesAwareModifierNode per consentire modificatori personalizzati basati sul posizionamento.
• Sono stati aggiunti metodi del ciclo di vita di collegamento/scollegamento a SubspaceModifier.Node.
• Aggiunta di scaleWithDistance al modificatore mobile. Quando scaleWithDistance è attivato, l'elemento dello spazio secondario spostato si ingrandisce o si riduce. Manterrà anche la scala esplicita che aveva prima dello spostamento.

Modifiche alle API

• SessionCallbackProvider rimosso a favore di SpatialCapabilities.

Altre modifiche

• Ridotto 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'ordinazione di SubspaceModifier. SubspaceModifier dovrebbe comportarsi in modo più affidabile. I modificatori Sposta, Ruota, Scala, Spostabile e Ridimensionabile ora dovrebbero essere utilizzabili in qualsiasi ordine.

Versione 1.0.0-alpha01

12 dicembre 2024

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

Funzionalità della versione iniziale

• Versione iniziale per sviluppatori di Jetpack Compose per XR. Utilizza concetti familiari di Compose come righe e colonne per creare layout dell'interfaccia utente spaziale in XR, sia che tu stia eseguendo il porting di un'app 2D esistente in XR sia che tu stia creando una nuova app XR da zero. Questa libreria fornisce composable spaziali e di sottospazio, come pannelli spaziali e orbiter, che ti consentono di posizionare la tua UI 2D Compose o basata su Views in un layout spaziale. Introduce il componente componibile Volume subspace, che consente di posizionare le entità SceneCore, come i modelli 3D, rispetto alla UI. Scopri di più in questa guida per gli sviluppatori:

  • Subspace: questo elemento componibile può essere posizionato ovunque all'interno della gerarchia dell'UI della tua app, consentendoti di mantenere i layout per l'UI 2D e spaziale senza perdere il contesto tra i file. In questo modo è più facile condividere elementi come l'architettura delle app esistenti tra XR e altri fattori di forma senza dover sollevare lo stato attraverso l'intero albero dell'interfaccia utente o riprogettare l'app.

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

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

  • Volume: posiziona le entità SceneCore, come i modelli 3D, rispetto alla tua UI.

• 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 attive.

  • SpatialDialog: il pannello si sposta leggermente indietro in profondità Z per visualizzare una finestra di dialogo in rilievo.
  • SpatialPopUp: il riquadro si sposta leggermente indietro in profondità Z per visualizzare un popup in rilievo
  • 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 il sistema o possono persino essere modificate dalla tua app, ad esempio passando allo spazio della casa o allo spazio completo. Per evitare problemi, la tua 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: se l'applicazione può controllare lo stato passthrough isSpatialAudioEnabled: audio spaziale

Problemi noti

• Al momento è necessario un minSDK di 30 per utilizzare Jetpack Compose per XR. Come soluzione alternativa, puoi aggiungere la seguente voce del manifest <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> per poter compilare ed eseguire con una minSDK di 23.
• Le app Jetpack XR attualmente richiedono la richiesta dell'autorizzazione android.permission.SCENE_UNDERSTANDING in AndroidManifest.
• Quando un'app viene avviata direttamente in Spazio completo utilizzando la proprietà PROPERTY_XR_ACTIVITY_START_MODE nel manifest, le attività/applicazioni vengono inizialmente aperte in Spazio personale prima di passare a Spazio completo.
• I glTF nei composable Volume potrebbero inizialmente sfarfallare nella posizione errata.
• L'utilizzo di una finestra di dialogo spaziale in un riquadro spostato in modo significativo sposterà i contenuti nella direzione sbagliata.