Ripartizione dei modificatori per fase

Jetpack Compose esegue i modificatori in fasi distinte. La seguente suddivisione mostra a quale fase appartengono i modificatori comuni e quando vengono valutati i relativi argomenti o lambda.

Fase 1: fase di composizione

Questi modificatori valutano gli argomenti in modo sincrono all'interno del corpo di @Composable. Qualsiasi stato letto qui registra una dipendenza con l'ambito di riavvio del componibile e attiva una ricomposizione completa quando viene modificato.

  • Modificatori di dimensioni e ridimensionamento statici:
    • Modifier.size(dp), Modifier.width(dp) e Modifier.height(dp)
    • Modifier.fillMaxSize(), Modifier.fillMaxWidth() e Modifier.fillMaxHeight()
    • Modifier.wrapContentSize(), Modifier.wrapContentWidth() e Modifier.wrapContentHeight()
    • Modifier.requiredSize(), Modifier.defaultMinSize()
    • Modifier.aspectRatio(ratio)
    • Modifier.weight(weight) (in RowScope o ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Spaziatura e rientri statici:
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Modificatori visivi del valore diretto:
    • Modifier.alpha(float) (legge lo stato durante la composizione)
    • Modifier.rotate(degrees) (legge lo stato durante la composizione)
    • Modifier.scale(scaleX, scaleY) (legge lo stato durante la composizione)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Modificatori di posizione statici:
    • Modifier.offset(x = dp, y = dp) (direct value overload)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Modificatori componibili dinamici:
    • Modifier.composed { ... } (esegue il corpo della factory durante la composizione; non consigliato per le prestazioni: utilizza invece Modifier.Node per i modificatori personalizzati)

Fase 2: fase di layout

La fase di layout è suddivisa in due passaggi secondari distinti con ambiti di invalidazione separati:

Passaggio 2A: misurazione

Determina le dimensioni (width, height) e i vincoli. La lettura dello stato qui attiva la nuova misurazione e il nuovo posizionamento:

  • Modifier.layout { measurable, constraints -> ... }: il codice prima di layout(w, h) viene eseguito durante la misurazione.

Passaggio 2B: callback di posizionamento e layout

Determina la posizione della coordinata (x, y). La lettura dello stato all'interno dei blocchi di posizionamento attiva solo il riposizionamento (saltando la misurazione e la composizione):

  • Modifier.offset { IntOffset(x, y) } (sovraccarico lambda)
  • Modifier.absoluteOffset { IntOffset(x, y) } (sovraccarico lambda)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: codice all'interno del blocco layout(w, h) { ... }.

Anche i callback di osservazione del layout vengono eseguiti durante o dopo la fase di layout (evita di scrivere nello stato letto in Composition all'interno di questi callback, poiché ciò causa scritture all'indietro):

  • Modifier.onSizeChanged { intSize -> ... }: viene richiamato al termine della misurazione del layout se le dimensioni del nodo sono cambiate.
  • Modifier.onPlaced { layoutCoordinates -> ... } e Modifier.onLayoutRectChanged { ... }: richiamati dopo il posizionamento per segnalare coordinate o limiti locali senza sottoscrivere i passaggi di layout della finestra globale.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: viene richiamato al termine dell'intero passaggio di layout della finestra ogni volta che un nodo viene spostato. Evita onGloballyPositioned quando possibile; preferisci Modifier.onVisibilityChanged per il monitoraggio dell'area visibile, Modifier.onPlaced o Modifier.onLayoutRectChanged per i limiti locali o requireLayoutCoordinates() on demand all'interno di un Modifier.Node.

Fase 3: fase di disegno

Questi modificatori vengono eseguiti durante il disegno del canvas. La lettura dello stato all'interno di questi blocchi salta sia la composizione che il layout, eseguendo solo la fase di disegno:

  • Modifier.graphicsLayer { ... }:
    • Proprietà aggiornate in lambda: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... }:
    • Disegna i comandi del canvas dietro i contenuti componibili.
  • Modifier.drawWithContent { ... }:
    • Controlla l'ordine di disegno con drawContent().
  • Modifier.drawWithCache { ... }:
    • Il blocco esterno viene eseguito in caso di modifiche alle dimensioni o al layout per memorizzare nella cache gli oggetti Path, Paint o Brush; onDrawBehind o onDrawWithContent viene eseguito su ogni disegno di frame.

Al di fuori del loop di ricomposizione: modificatori di osservazione

Alcuni modificatori operano al di fuori delle tre fasi del frame per gestire l'accessibilità, l'input utente e le osservazioni del ciclo di vita.

Semantica e accessibilità

Elabora le proprietà semantiche per i servizi di accessibilità (TalkBack) e i test:

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

Input, gesti ed eventi

Opera al di fuori della pipeline di rendering dei frame in tre fasi, ricevendo eventi di movimento del sistema operativo e interazioni dell'utente:

  • 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 -> ... }: il callback viene richiamato quando la visibilità di un componibile cambia dopo il ritardo configurato, in una coroutine.

Riferimento rapido: fase Valore e fase Lambda

La lettura di un valore di stato in una funzione lambda rimanda la lettura a una fase successiva, il che salta le fasi precedenti quando lo stato cambia:

Modificatore / pattern Valore diretto (composizione) Variante Lambda (fase differita) Quando lo stato cambia
Offset Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Layout (posizionamento) (salta la composizione)
Alpha / Opacità Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Disegno (salta Composizione e Layout)
Rotazione Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Disegno (salta Composizione e Layout)
Scala Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Disegno (salta Composizione e Layout)
Translation Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Disegno (salta Composizione e Layout)
Colore sfondo Modifier.background(color) Modifier.drawBehind { drawRect(color) } Disegno (salta Composizione e Layout)
Scorrimento / Parallasse Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Layout (posizionamento) (salta la composizione)

Mappatura dell'interfaccia Modifier.Node

Per i modificatori personalizzati che utilizzano l'API Modifier.Node ad alte prestazioni, le fasi vengono mappate direttamente alle interfacce delle funzionalità dei nodi:

Fase Interfaccia Modifier.Node Metodi principali
Layout (misura e posiziona) LayoutModifierNode measure(measurable, constraints)
Layout (coordinate globali) GlobalPositionAwareModifierNode (preferisci requireLayoutCoordinates() on demand) onGloballyPositioned(coordinates)
Layout (posizionamento) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Disegno DrawModifierNode draw(ContentDrawScope)
Input / puntatore PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Semantica SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Messa a fuoco FocusEventModifierNode onFocusEvent(focusState)