Comprendre les modificateurs de sous-espace

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 SubspaceModifier est semblable à un modificateur Compose pour les composables d'un Subspace. Un SubspaceModifier vous permet de manipuler des composables dans un espace 3D, ce qui vous aide à positionner, faire pivoter et ajouter des comportements aux nœuds de mise en page 3D.

Mise en page

Par défaut, un Subspace est limité par l'espace recommandé pour l'affichage d'une application. Ces limites sont utilisées pour mesurer la mise en page de vos composants de sous-espace, comme les limites dans les mises en page Compose 2D.

Limites de remplissage

Les modificateurs fillMaxSize, fillMaxWidth, fillMaxHeight et fillMaxDepth permettent au contenu de remplir (partiellement) les limites de son parent. L'utilisation de modificateurs de remplissage aide votre application à disposer le contenu indépendamment des caractéristiques d'affichage de l'appareil XR.

Définir la taille et la taille requise

Les modificateurs size, width, height et depth déclarent la taille préférée du contenu. Pour déclarer la taille exacte du contenu, utilisez requiredSize, requiredWidth, requiredHeight et requiredDepth. Ces unités doivent être spécifiées en dp. Pour convertir des mètres en dp, utilisez Meter.toDp().

Positionner des composables

offset

Le modificateur offset déplace le composable dans l'espace 3D le long des axes x, y et z. Ces unités doivent être spécifiées en dp. Pour convertir des mètres en dp, utilisez Meter.toDp().

rotate

Le modificateur rotate fait pivoter le composable donné dans l'espace. Vous pouvez spécifier la direction et l'angle de rotation de différentes manières :

  • En utilisant le tangage, le lacet et le roulis, qui spécifient respectivement la rotation autour des axes x, y et z.
  • En utilisant un axisAngle, qui est un Vector3 représentant l'axe de rotation, et le nombre de degrés de rotation autour de cet axe.
  • Utiliser un Quaternion qui représente la rotation.

rotateToLookAtUser

Le modificateur rotateToLookAtUser fait pivoter le contenu en continu pour qu'il soit toujours orienté vers l'utilisateur. Vous pouvez également utiliser ce modificateur pour obtenir un effet "panneau d'affichage" où le contenu pivote pour faire face à l'utilisateur sur l'axe Y, tout en restant droit et aligné avec la gravité. Pour ce faire, combinez le modificateur rotateToLookAtUser avec le modificateur gravityAligned.

Déplacer et redimensionner des composables

Permettez aux utilisateurs de manipuler directement la position et la taille des objets dans l'espace 3D.

Déplacer des éléments

Lorsque le modificateur movable est présent et activé, des commandes d'interface utilisateur déplaçables s'affichent, permettant à l'utilisateur de déplacer l'élément dans l'espace 3D. Vous pouvez appliquer des modificateurs movable à l'ensemble d'un Subspace, à des composants de mise en page spatiaux (comme SpatialRow et SpatialColumn) et à des composants individuels (comme SpatialPanel et SpatialGltfModel).

Le comportement spécifique de ce mouvement est défini par le movePolicy fourni :

  • MovePolicy.Default (ou MovePolicy.system()) : le système gère entièrement le mouvement, et calcule et applique automatiquement la nouvelle pose et la nouvelle échelle en fonction de l'entrée utilisateur.
  • MovePolicy.custom() : le système calcule la valeur Pose cible en fonction de l'entrée, mais ne l'applique pas automatiquement à l'élément associé. Cela est utile pour limiter les mouvements ou créer des mouvements personnalisés dans votre application.
  • MovePolicy.anchor() : permet à l'utilisateur d'ancrer l'élément mobile sur des plans réels détectés.

Composables d'ancrage

Pour pouvoir ancrer un composable de sous-espace déplaçable sur des surfaces réelles, transmettez MovePolicy.anchor() au modificateur movable. Cette règle permet aux utilisateurs d'ancrer des éléments (comme SpatialPanel et SpatialGltfModel) sur des surfaces physiques telles que des tables, des murs ou des sols.

Vous pouvez filtrer les plans détectés auxquels un élément peut s'ancrer à l'aide des paramètres suivants (si vous ne spécifiez rien, l'élément peut s'ancrer à n'importe quel plan détecté) :

  • anchorPlaneOrientations : ensemble de valeurs PlaneOrientation (Horizontal, Vertical ou Any).
  • anchorPlaneSemantics : ensemble de valeurs PlaneSemantic (Wall, Floor, Ceiling, Table ou Any).

Redimensionner des éléments

Lorsque le modificateur resizable() est présent et activé, des commandes d'interface utilisateur s'affichent pour permettre à l'utilisateur de redimensionner l'élément dans l'espace 3D. Le comportement spécifique du redimensionnement est défini par le resizePolicy fourni :

  • ResizePolicy.default() : le système gère automatiquement le geste de redimensionnement et applique les nouvelles dimensions au contenu.
  • ResizePolicy.custom() : le système fournit un SpatialResizeEvent et n'applique pas automatiquement le résultat du redimensionnement à l'élément associé.

Modifier l'apparence des composables

alpha

Le modificateur alpha définit l'opacité de l'élément et de ses enfants, où 0f représente une transparence totale et 1.0f une opacité totale.

scale

Le modificateur scale met à l'échelle le contenu du composable le long des axes horizontal, vertical et de profondeur.

Tests et accessibilité

semantics

Le modificateur semantics ajoute de la sémantique au nœud de mise en page, pour une utilisation dans les tests et l'accessibilité. Consultez Sémantique dans Jetpack Compose et SemanticsModifier.

testTag

Le modificateur testTag est un raccourci pour SemanticsPropertyReceiver.testTag, qui permet aux frameworks de test de trouver l'élément dans les tests.