Avec Jetpack Compose pour XR, vous pouvez créer de manière déclarative votre UI spatiale et votre mise en page à l'aide de concepts Compose familiers tels que les lignes et les colonnes. Vous pouvez ainsi étendre votre UI Android existante dans un espace 3D ou créer des applications 3D immersives entièrement nouvelles.
Si vous spatialisez une application Android basée sur les vues, plusieurs options de développement s'offrent à vous. Vous pouvez utiliser des API d'interopérabilité, Compose et Views ensemble, ou travailler directement avec la bibliothèque SceneCore. Pour en savoir plus, consultez notre guide sur l'utilisation des vues.
À propos des sous-espaces et des composants spatialisés
Lorsque vous écrivez votre application pour Android XR, il est important de comprendre les concepts d'sous-espace et de composants spatialisés.
À propos du sous-espace
Lorsque vous développez pour Android XR, vous devez ajouter un sous-espace à votre application ou à votre mise en page. Un sous-espace est une partition de l'espace 3D de votre application dans laquelle vous pouvez placer du contenu 3D, créer des mises en page 3D et ajouter de la profondeur à du contenu 2D. Un sous-espace n'est affiché que lorsque la spatialisation est activée. Dans Home Space ou sur les appareils non XR, tout code de ce sous-espace est ignoré.
Il existe deux façons de créer un sous-espace:
setSubspaceContent()
: cette fonction crée un sous-espace au niveau de l'application. Vous pouvez l'appeler dans votre activité principale de la même manière que vous utilisezsetContent()
. Un sous-espace au niveau de l'application est illimité en hauteur, largeur et profondeur, fournissant essentiellement un canevas infini pour le contenu spatial.Subspace
: ce composable peut être placé n'importe où dans la hiérarchie de l'interface utilisateur de votre application, ce qui vous permet de conserver les mises en page pour l'UI 2D et spatiale sans perdre de contexte entre les fichiers. Cela permet de partager plus facilement des éléments tels que l'architecture d'application existante entre la RA et d'autres facteurs de forme, sans avoir à hisser l'état dans l'ensemble de l'arborescence de l'UI ni à réarchitecturer votre application.
Pour en savoir plus, consultez Ajouter un sous-espace à votre application.
À propos des composants spatialisés
Composables de sous-espace: ces composants ne peuvent être affichés que dans un sous-espace.
Ils doivent être inclus dans Subspace
ou setSubspaceContent
avant d'être placés dans une mise en page 2D. Un SubspaceModifier
vous permet d'ajouter des attributs tels que la profondeur, le décalage et le positionnement à vos composables d'espaces sous-jacents.
Les autres composants spatialisés n'ont pas besoin d'être appelés dans un sous-espace. Ils se composent d'éléments 2D conventionnels encapsulés dans un conteneur spatial. Ces éléments peuvent être utilisés dans des mises en page 2D ou 3D s'ils sont définis pour les deux. Lorsque la spatialisation n'est pas activée, leurs éléments spatialisés sont ignorés et ils reviennent à leurs homologues 2D.
Créer un panneau spatial
Un SpatialPanel
est un composable d'espace sous-jacent qui vous permet d'afficher le contenu de l'application. Par exemple, vous pouvez afficher la lecture vidéo, des images fixes ou tout autre contenu dans un panneau spatial.
Vous pouvez utiliser SubspaceModifier
pour modifier la taille, le comportement et le positionnement du panneau spatial, comme illustré dans l'exemple suivant.
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
)
}
}
Points clés concernant le code
- Étant donné que les API
SpatialPanel
sont des composables de sous-espace, vous devez les appeler dansSubspace
ousetSubspaceContent
. Les appeler en dehors d'un sous-espace génère une exception. - Autorisez l'utilisateur à redimensionner ou à déplacer le panneau en ajoutant les modificateurs
movable
ouresizable
. - Pour en savoir plus sur le dimensionnement et le positionnement, consultez nos conseils de conception pour les panneaux spatiaux. Pour en savoir plus sur l'implémentation du code, consultez notre documentation de référence.
Créer un orbiteur
Un orbiteur est un composant d'UI spatial. Il est conçu pour être associé à un panneau spatial, une mise en page ou une autre entité correspondante. Un orbiteur contient généralement des éléments de navigation et d'action contextuels liés à l'entité à laquelle il est ancré. Par exemple, si vous avez créé un panneau spatial pour afficher du contenu vidéo, vous pouvez ajouter des commandes de lecture vidéo dans un orbiteur.
Comme illustré dans l'exemple suivant, appelez un orbiteur dans la mise en page 2D dans un SpatialPanel
pour encapsuler les commandes utilisateur telles que la navigation. Vous les extrayez ainsi de votre mise en page 2D et les associez au panneau spatial en fonction de votre configuration.
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
)
}
}
}
}
Points clés concernant le code
- Étant donné que les orbiteurs sont des composants d'UI spatiaux, le code peut être réutilisé dans des mises en page 2D ou 3D. Dans une mise en page 2D, votre application n'affiche que le contenu dans l'orbiteur et ignore l'orbiteur lui-même.
- Pour en savoir plus sur l'utilisation et la conception des orbiteurs, consultez nos conseils de conception.
Ajouter plusieurs panneaux spatiaux à une mise en page spatiale
Vous pouvez créer plusieurs panneaux spatiaux et les placer dans une mise en page spatiale à l'aide de SpatialRow
, SpatialColumn
, SpatialBox
et SpatialLayoutSpacer
.
L'exemple de code suivant montre comment procéder.
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
)
}
}
Points clés concernant le code
SpatialRow
,SpatialColumn
,SpatialBox
etSpatialLayoutSpacer
sont tous des composables de sous-espace et doivent être placés dans un sous-espace.- Utilisez
SubspaceModifier
pour personnaliser votre mise en page. - Pour les mises en page comportant plusieurs panneaux sur une ligne, nous vous recommandons de définir un rayon de courbe de 825 dp à l'aide d'un
SubspaceModifier
afin que les panneaux entourent l'utilisateur. Pour en savoir plus, consultez nos conseils de conception.
Utiliser un volume pour placer un objet 3D dans votre mise en page
Pour placer un objet 3D dans votre mise en page, vous devez utiliser un composable d'espace sous-jacent appelé volume. Voici un exemple de la procédure à suivre.
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
}
}
}
}
}
Points clés concernant le code
- Consultez Ajouter des modèles 3D à votre application pour mieux comprendre comment charger du contenu 3D dans un volume.
Ajouter d'autres composants d'interface utilisateur spatial
Les composants d'interface utilisateur spatiale peuvent être placés n'importe où dans la hiérarchie de l'interface utilisateur de votre application. Ces éléments peuvent être réutilisés dans votre UI 2D, et leurs attributs spatiaux ne seront visibles que lorsque les fonctionnalités spatiales sont activées. Vous pouvez ainsi ajouter une élévation aux menus, aux boîtes de dialogue et à d'autres composants sans avoir à écrire votre code deux fois. Consultez les exemples d'UI spatiale suivants pour mieux comprendre comment utiliser ces éléments.
Composant d'interface utilisateur |
Lorsque la spatialisation est activée |
Dans un environnement 2D |
---|---|---|
|
Le panneau est légèrement repoussé en arrière dans la profondeur de champ pour afficher une boîte de dialogue surélevée. |
Revenir en mode 2D |
|
Le panneau est légèrement repoussé en arrière dans la profondeur de champ pour afficher un pop-up surélevé. |
Retourne à une |
|
|
Émissions sans élévation spatiale. |
SpatialDialog
Voici un exemple de boîte de dialogue qui s'ouvre après un court délai. Lorsque SpatialDialog
est utilisé, la boîte de dialogue s'affiche à la même profondeur Z que le panneau spatial, et le panneau est repoussé de 125 dp lorsque la spatialisation est activée. SpatialDialog
peut également être utilisé lorsque la spatialisation n'est pas activée, auquel cas SpatialDialog
revient à son homologue 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")
}
}
}
}
}
Points clés concernant le code
- Voici un exemple de
SpatialDialog
. L'utilisation deSpatialPopUp
et deSpatialElevation
est très similaire. Pour en savoir plus, consultez notre documentation de référence de l'API.
Créer des panneaux et des mises en page personnalisés
Pour créer des panneaux personnalisés non compatibles avec Compose pour XR, vous pouvez travailler directement avec PanelEntities
et le graphique de scène à l'aide des API SceneCore
.
Ancrer des orbiteurs à des mises en page spatiales et à d'autres entités
Vous pouvez ancrer un orbiteur à n'importe quelle entité déclarée dans Compose. Pour ce faire, déclarez un orbiteur dans une mise en page spatiale d'éléments d'interface utilisateur tels que SpatialRow
, SpatialColumn
ou SpatialBox
. L'orbiteur s'ancre à l'entité parente la plus proche de l'endroit où vous l'avez déclaré.
Le comportement de l'orbiteur est déterminé par l'endroit où vous le déclarez:
- Dans une mise en page 2D encapsulée dans un
SpatialPanel
(comme illustré dans un extrait de code précédent), l'orbiteur s'ancre à cet élémentSpatialPanel
. - Dans un
Subspace
, l'orbiteur s'ancre à l'entité parente la plus proche, qui correspond à la mise en page spatiale dans laquelle l'orbiteur est déclaré.
L'exemple suivant montre comment ancrer un orbiteur à une ligne spatiale:
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)
)
}
}
}
Points clés concernant le code
- Lorsque vous déclarez un orbiteur en dehors d'une mise en page 2D, il s'ancre à l'entité parente la plus proche. Dans ce cas, l'orbiteur s'ancre en haut de l'
SpatialRow
dans lequel il est déclaré. - Les mises en page spatiales telles que
SpatialRow
,SpatialColumn
etSpatialBox
sont toutes associées à des entités sans contenu. Par conséquent, un orbiteur déclaré dans une mise en page spatiale s'ancre à cette mise en page.
Voir aussi
- Ajouter des modèles 3D à votre application
- Développer une UI pour les applications Android basées sur des vues
- Implémenter Material Design pour XR