Panneaux spatiaux

Appareils XR concernés
Ces conseils vous aideront à créer des expériences pour ces types d'appareils XR.
En savoir plus sur les types d'appareils XR →
Casques XR
Lunettes XR filaires
En savoir plus sur les types d'appareils XR →

Un SpatialPanel est un composable de sous-espace qui vous permet d'afficher le contenu de votre application. Par exemple, vous pouvez afficher une lecture vidéo, des images fixes ou tout autre contenu dans un panneau spatial.

Figure 1.: Exemple de panneau d'UI spatiale.

Vous pouvez utiliser SubspaceModifier pour modifier la taille, le comportement et le positionnement du panneau spatial.

Créer un panneau spatial

L'exemple suivant montre comment créer un panneau spatial.

Subspace {
    SpatialPanel(
        SubspaceModifier
            .height(824.dp)
            .width(1400.dp)
            .movable()
            .resizable(),
    ) {
        SpatialPanelContent()
    }
}

@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 dans Subspace. Leur appel en dehors d'un sous-espace génère une exception.
  • La taille de SpatialPanel a été définie à l'aide des spécifications height et width sur SubspaceModifier. Si vous omettez ces spécifications, la taille du panneau est déterminée par les mesures de son contenu.
  • Autorisez l'utilisateur à déplacer un panneau en ajoutant un modificateur de sous-espace movable.
  • Autorisez l'utilisateur à redimensionner un panneau en ajoutant un modificateur de sous-espace resizable.
  • 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.

Fonctionnement du modificateur movable

Lorsqu'un utilisateur éloigne un panneau, le modificateur movable redimensionne par défaut le panneau de la même manière que le système redimensionne les panneaux dans l'espace d'accueil. Tous les contenus enfants héritent de ce comportement. Pour désactiver cette option, définissez le paramètre shouldScaleWithDistance sur false.

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 SpatialSpacer.

Figure 2 : Exemple de plusieurs panneaux spatiaux dans une mise en page spatiale.

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 et SpatialSpacer 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 courbure de 825 dp à l'aide d'un SubspaceModifier afin que les panneaux entourent l'utilisateur. Pour en savoir plus, consultez nos conseils de conception.

Créer des panneaux et des mises en page personnalisés

Pour créer des panneaux personnalisés qui ne sont pas compatibles avec Compose pour XR, vous pouvez travailler directement avec des instances PanelEntity et le graphe de scène à l'aide des API SceneCore.