Modifier la répartition par phase

Jetpack Compose exécute les modificateurs en plusieurs phases distinctes. La répartition suivante montre à quelle phase appartiennent les modificateurs courants et quand leurs arguments ou lambdas sont évalués.

Phase 1 : Phase de composition

Ces modificateurs évaluent les arguments de manière synchrone dans le corps @Composable. Tout état lu ici enregistre une dépendance avec le champ d'application de redémarrage du composable et déclenche une recomposition complète en cas de modification.

  • Modificateurs de dimension et de taille statiques :
    • Modifier.size(dp), Modifier.width(dp), Modifier.height(dp)
    • Modifier.fillMaxSize(), Modifier.fillMaxWidth(), Modifier.fillMaxHeight()
    • Modifier.wrapContentSize(), Modifier.wrapContentWidth(), Modifier.wrapContentHeight()
    • Modifier.requiredSize(), Modifier.defaultMinSize()
    • Modifier.aspectRatio(ratio)
    • Modifier.weight(weight) (en RowScope ou ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Espacement et encarts statiques :
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Modificateurs visuels de valeur directe :
    • Modifier.alpha(float) (lit l'état pendant la composition)
    • Modifier.rotate(degrees) (lit l'état pendant la composition)
    • Modifier.scale(scaleX, scaleY) (lit l'état pendant la composition)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Modificateurs de position statiques :
    • Modifier.offset(x = dp, y = dp) (surcharge de valeur directe)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Modificateurs composables dynamiques :
    • Modifier.composed { ... } (exécute le corps de la fabrique pendant la composition ; non recommandé pour les performances : utilisez plutôt Modifier.Node pour les modificateurs personnalisés)

Phase 2 : Mise en page

La phase de mise en page est divisée en deux sous-étapes distinctes avec des champs d'invalidation distincts :

Étape 2A : Mesure

Détermine la taille (width, height) et les contraintes. La lecture de l'état déclenche ici une nouvelle mesure et un nouveau positionnement :

  • Modifier.layout { measurable, constraints -> ... } : le code avant layout(w, h) s'exécute pendant la mesure.

Étape 2B : Rappels de positionnement et de mise en page

Détermine la position de la coordonnée (x, y). La lecture de l'état dans les blocs de positionnement ne déclenche que le repositionnement (en ignorant la mesure et la composition) :

  • Modifier.offset { IntOffset(x, y) } (surcharge lambda)
  • Modifier.absoluteOffset { IntOffset(x, y) } (surcharge lambda)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } } : code à l'intérieur du bloc layout(w, h) { ... }.

Les rappels d'observation de la mise en page s'exécutent également pendant ou après la passe de mise en page (évitez d'écrire dans l'état lu dans la composition à l'intérieur de ces rappels, car cela entraîne des écritures rétrogrades) :

  • Modifier.onSizeChanged { intSize -> ... } : appelé une fois la mesure de la mise en page terminée si les dimensions du nœud ont changé.
  • Modifier.onPlaced { layoutCoordinates -> ... } et Modifier.onLayoutRectChanged { ... } : appelés après l'emplacement pour signaler les coordonnées ou les limites locales sans s'abonner aux passes de mise en page de la fenêtre globale.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... } : appelé une fois que l'intégralité de la mise en page de la fenêtre est terminée, chaque fois qu'un nœud est déplacé. Évitez onGloballyPositioned dans la mesure du possible. Privilégiez Modifier.onVisibilityChanged pour le suivi de la fenêtre d'affichage, Modifier.onPlaced ou Modifier.onLayoutRectChanged pour les limites locales, ou requireLayoutCoordinates() à la demande dans un Modifier.Node.

Phase 3 : Phase de dessin

Ces modificateurs s'exécutent pendant le dessin du canevas. La lecture de l'état dans ces blocs ignore la composition et la mise en page, et n'exécute que la phase de dessin :

  • Modifier.graphicsLayer { ... } :
    • Propriétés mises à jour dans lambda : alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... } :
    • Permet de dessiner des commandes de canevas derrière le contenu du composable.
  • Modifier.drawWithContent { ... } :
    • Contrôle l'ordre de dessin avec drawContent().
  • Modifier.drawWithCache { ... } :
    • Le bloc externe s'exécute lors des modifications de taille ou de mise en page pour mettre en cache les objets Path, Paint ou Brush. onDrawBehind ou onDrawWithContent s'exécute à chaque dessin de frame.

En dehors de la boucle de recomposition : modificateurs d'observation

Certains modificateurs fonctionnent en dehors des trois phases de frame pour gérer l'accessibilité, les entrées utilisateur et les observations du cycle de vie.

Sémantique et accessibilité

Traite les propriétés sémantiques pour les services d'accessibilité (TalkBack) et les tests :

  • Modifier.semantics { ... }
  • Modifier.clearAndSetSemantics { ... }

Saisie, gestes et événements

Fonctionne en dehors du pipeline de rendu de frame en trois phases, en recevant les événements de mouvement de l'OS et les interactions utilisateur :

  • Modifier.pointerInput(key) { detectTapGestures { ... } } / detectDragGestures / awaitPointerEventScope
  • Modifier.clickable(enabled, onClickLabel) { ... }
  • Modifier.combinedClickable { ... }
  • Modifier.toggleable { ... }
  • Modifier.selectable { ... }
  • Modifier.draggable(...) / Modifier.scrollable(...) / Modifier.draggable2D(...)
  • Modifier.onFocusChanged { focusState -> ... }
  • Modifier.onKeyEvent { keyEvent -> ... }
  • Modifier.onVisibilityChanged { isVisible -> ... } : le rappel est appelé lorsque la visibilité d'un composable change après un délai configuré, dans une coroutine.

Référence rapide : phase de valeur et phase lambda

La lecture d'une valeur d'état dans un lambda reporte la lecture à une phase ultérieure, ce qui ignore les phases précédentes lorsque cet état change :

Modificateur / Modèle Valeur directe (composition) Variante Lambda (phase différée) Lorsque l'état change
Décalage (offset) Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Layout (Placement) (ignore la composition)
Alpha / Opacité Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Dessin (ignore la composition et la mise en page)
Rotation Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Dessin (ignore la composition et la mise en page)
Évoluer Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Dessin (ignore la composition et la mise en page)
Translation Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Dessin (ignore la composition et la mise en page)
Couleur de l'arrière-plan Modifier.background(color) Modifier.drawBehind { drawRect(color) } Dessin (ignore la composition et la mise en page)
Défilement / Parallaxe Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Layout (Placement) (ignore la composition)

Mappage de l'interface Modifier.Node

Pour les modificateurs personnalisés utilisant l'API Modifier.Node hautes performances, les phases sont directement mappées aux interfaces de fonctionnalités des nœuds :

Phase Interface Modifier.Node Méthodes principales
Mise en page (mesure et placement) LayoutModifierNode measure(measurable, constraints)
Mise en page (coordonnées globales) GlobalPositionAwareModifierNode (privilégiez requireLayoutCoordinates() à la demande) onGloballyPositioned(coordinates)
Layout (Placement) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Dessin DrawModifierNode draw(ContentDrawScope)
Saisie / Pointeur PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Sémantique SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Mise au point FocusEventModifierNode onFocusEvent(focusState)