Detalhamento do modificador por fase

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) (em RowScope ou ColumnScope)
    • 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. Use Modifier.Node para 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 de layout(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 bloco layout(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 -> ... } e Modifier.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. Evite onGloballyPositioned quando possível. Prefira Modifier.onVisibilityChanged para rastreamento de janela de visualização, Modifier.onPlaced ou Modifier.onLayoutRectChanged para limites locais ou requireLayoutCoordinates() sob demanda dentro de um Modifier.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.
  • Modifier.drawBehind { ... }:
    • Desenha comandos de tela atrás do conteúdo combinável.
  • Modifier.drawWithContent { ... }:
    • Controla a ordem de desenho com drawContent().
  • Modifier.drawWithCache { ... }:
    • O bloco externo é executado em mudanças de tamanho ou layout para armazenar em cache objetos Path, Paint ou Brush. onDrawBehind ou onDrawWithContent é executado em cada desenho de frame.

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 / 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 -> ... }: 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)