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)eModifier.height(dp)Modifier.fillMaxSize(),Modifier.fillMaxWidth()eModifier.fillMaxHeight()Modifier.wrapContentSize(),Modifier.wrapContentWidth()eModifier.wrapContentHeight()Modifier.requiredSize(),Modifier.defaultMinSize()Modifier.aspectRatio(ratio)Modifier.weight(weight)(inRowScopeoColumnScope)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 inveceModifier.Nodeper 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 dilayout(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 bloccolayout(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 -> ... }eModifier.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. EvitaonGloballyPositionedquando possibile; preferisciModifier.onVisibilityChangedper il monitoraggio dell'area visibile,Modifier.onPlacedoModifier.onLayoutRectChangedper i limiti locali orequireLayoutCoordinates()on demand all'interno di unModifier.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.
- Proprietà aggiornate in lambda:
Modifier.drawBehind { ... }:- Disegna i comandi del canvas dietro i contenuti componibili.
Modifier.drawWithContent { ... }:- Controlla l'ordine di disegno con
drawContent().
- Controlla l'ordine di disegno con
Modifier.drawWithCache { ... }:- Il blocco esterno viene eseguito in caso di modifiche alle dimensioni o al layout per memorizzare nella cache gli oggetti
Path,PaintoBrush;onDrawBehindoonDrawWithContentviene eseguito su ogni disegno di frame.
- Il blocco esterno viene eseguito in caso di modifiche alle dimensioni o al layout per memorizzare nella cache gli oggetti
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/awaitPointerEventScopeModifier.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) |