O Jetpack Compose executa modificadores em fases distintas. A análise a seguir mostra a qual fase os modificadores comuns pertencem e quando os argumentos ou lambdas deles são avaliados.
Fase 1: composição
Esses modificadores avaliam argumentos de forma síncrona dentro do corpo de
@Composable. Qualquer estado lido aqui registra uma dependência com o escopo de reinicialização
do elemento combinável e aciona uma recomposição completa quando modificado.
- Modificadores de dimensão e tamanho estáticos:
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)(emRowScopeouColumnScope)Modifier.width(IntrinsicSize.Min / Max)Modifier.height(IntrinsicSize.Min / Max)
- Espaçamento estático e inserções:
Modifier.padding(all = dp),Modifier.padding(start, top, end, bottom)Modifier.windowInsetsPadding(insets),Modifier.statusBarsPadding()
- Modificadores visuais de valor direto:
Modifier.alpha(float)(lê o estado durante a composição)Modifier.rotate(degrees)(lê o estado durante a composição)Modifier.scale(scaleX, scaleY)(lê o estado durante a composição)Modifier.background(color = Color, shape = Shape)Modifier.border(width, color, shape)Modifier.shadow(elevation, shape)Modifier.clip(shape)Modifier.blur(radius)
- Modificadores de posição estática:
Modifier.offset(x = dp, y = dp)(sobrecarga de valor direto)Modifier.absoluteOffset(x = dp, y = dp)
- Modificadores dinâmicos de composição:
Modifier.composed { ... }(executa o corpo da fábrica durante a composição; não recomendado para desempenho. UseModifier.Nodepara modificadores personalizados)
Fase 2: fase de layout
A fase de layout é dividida em duas subetapas distintas com escopos de invalidação separados:
Etapa 2A: medição
Determina o tamanho (width, height) e as restrições. A leitura do estado aqui
aciona a remedição e o reposicionamento:
Modifier.layout { measurable, constraints -> ... }: o código antes delayout(w, h)é executado durante a medição.
Etapa 2B: callbacks de posicionamento e layout
Determina a posição da coordenada (x, y). A leitura de estado dentro de blocos de posicionamento
aciona apenas o reposicionamento (pulando a medição e a composição):
Modifier.offset { IntOffset(x, y) }(sobrecarga de lambda)Modifier.absoluteOffset { IntOffset(x, y) }(sobrecarga de lambda)Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: código dentro do blocolayout(w, h) { ... }.
Os callbacks de observação de layout também são executados durante ou após a passagem de layout. Evite gravar no estado que é lido na composição dentro desses callbacks, porque isso causa gravações reversas:
Modifier.onSizeChanged { intSize -> ... }: invocado após a conclusão da medição do layout, se as dimensões do nó mudarem.Modifier.onPlaced { layoutCoordinates -> ... }eModifier.onLayoutRectChanged { ... }: invocados após o posicionamento para informar coordenadas ou limites locais sem se inscrever em transmissões de layout de janela global.Modifier.onGloballyPositioned { layoutCoordinates -> ... }: invocado depois que toda a passagem de layout da janela é concluída sempre que um nó se move. EviteonGloballyPositionedquando possível. PrefiraModifier.onVisibilityChangedpara rastreamento de janela de visualização,Modifier.onPlacedouModifier.onLayoutRectChangedpara limites locais ourequireLayoutCoordinates()sob demanda dentro de umModifier.Node.
Fase 3: fase de exibição
Esses modificadores são executados durante o desenho da tela. A leitura de estado dentro desses blocos ignora a composição e o layout, executando apenas a passagem de exibição:
Modifier.graphicsLayer { ... }:- Propriedades atualizadas em lambda:
alpha,translationX,translationY,scaleX,scaleY,rotationX,rotationY,rotationZ,shadowElevation,shape,clip,renderEffect,transformOrigin.
- Propriedades atualizadas em lambda:
Modifier.drawBehind { ... }:- Desenha comandos de tela atrás do conteúdo combinável.
Modifier.drawWithContent { ... }:- Controla a ordem de desenho com
drawContent().
- Controla a ordem de desenho com
Modifier.drawWithCache { ... }:- O bloco externo é executado em mudanças de tamanho ou layout para armazenar em cache objetos
Path,PaintouBrush.onDrawBehindouonDrawWithContenté executado em cada desenho de frame.
- O bloco externo é executado em mudanças de tamanho ou layout para armazenar em cache objetos
Fora do loop de recomposição: modificadores de observação
Alguns modificadores operam fora das três fases de frame para processar acessibilidade, entrada do usuário e observações do ciclo de vida.
Semântica e acessibilidade
Processa propriedades semânticas para serviços de acessibilidade (TalkBack) e testes:
Modifier.semantics { ... }Modifier.clearAndSetSemantics { ... }
Entrada, gestos e eventos
Opera fora do pipeline de renderização de frames de três fases, recebendo eventos de movimento do SO e interações do usuário:
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 -> ... }: o callback é invocado quando a visibilidade de um elemento combinável muda após o atraso configurado, em uma corrotina.
Referência rápida: fase de valor x fase lambda
A leitura de um valor de estado em uma lambda adia a leitura para uma fase posterior, o que pula as fases anteriores quando esse estado muda:
| Modificador / Padrão | Valor direto (composição) | Variante Lambda (fase adiada) | Quando o estado muda |
|---|---|---|---|
| Deslocamento | Modifier.offset(x, y) |
Modifier.offset { IntOffset(x, y) } |
Layout (posicionamento) (pula a composição) |
| Alfa / Opacidade | Modifier.alpha(alpha) |
Modifier.graphicsLayer { this.alpha = alpha } |
Desenho (pula a composição e o layout) |
| Rotação | Modifier.rotate(degrees) |
Modifier.graphicsLayer { rotationZ = degrees } |
Desenho (pula a composição e o layout) |
| Escala | Modifier.scale(scale) |
Modifier.graphicsLayer { scaleX = s; scaleY = s } |
Desenho (pula a composição e o layout) |
| Tradução | Modifier.padding(...) |
Modifier.graphicsLayer { translationX = ... } |
Desenho (pula a composição e o layout) |
| Cor do plano de fundo | Modifier.background(color) |
Modifier.drawBehind { drawRect(color) } |
Desenho (pula a composição e o layout) |
| Rolagem / Paralaxe | Modifier.offset(scroll.dp) |
Modifier.offset { IntOffset(0, scroll) } |
Layout (posicionamento) (pula a composição) |
Mapeamento da interface Modifier.Node
Para modificadores personalizados que usam a API Modifier.Node de alto desempenho, as fases são mapeadas
diretamente para as interfaces de capacidade do nó:
| Fase | Interface Modifier.Node |
Métodos principais |
|---|---|---|
| Layout (medição e posicionamento) | LayoutModifierNode |
measure(measurable, constraints) |
| Layout (coordenadas globais) | GlobalPositionAwareModifierNode (preferir requireLayoutCoordinates() on demand) |
onGloballyPositioned(coordinates) |
| Layout (posição) | LayoutAwareModifierNode |
onRemeasured(size), onPlaced(coordinates) |
| Desenho | DrawModifierNode |
draw(ContentDrawScope) |
| Entrada / Ponteiro | PointerInputModifierNode |
onPointerEvent(...), onCancelPointerInput() |
| Semântica | SemanticsModifierNode |
applySemantics(SemanticsPropertyReceiver) |
| Foco | FocusEventModifierNode |
onFocusEvent(focusState) |