Zestawienie modyfikatorów według etapu

Jetpack Compose wykonuje modyfikatory w różnych fazach. Poniższe zestawienie pokazuje, do której fazy należą typowe modyfikatory i kiedy są oceniane ich argumenty lub funkcje lambda.

Faza 1. Faza kompozycji

Te modyfikatory oceniają argumenty synchronicznie wewnątrz treści @Composable. Każdy odczytany tutaj stan rejestruje zależność z zakresem ponownego uruchomienia funkcji kompozycyjnej i po zmianie wywołuje pełną rekompozycję.

  • Modyfikatory statycznego wymiaru i rozmiaru:
    • 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) (w RowScope lub ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Statyczne odstępy i wstawki:
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Modyfikatory wizualne wartości bezpośredniej:
    • Modifier.alpha(float) (odczytuje stan podczas tworzenia wiadomości)
    • Modifier.rotate(degrees) (odczytuje stan podczas tworzenia wiadomości)
    • Modifier.scale(scaleX, scaleY) (odczytuje stan podczas tworzenia wiadomości)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Modyfikatory pozycji statycznej:
    • Modifier.offset(x = dp, y = dp) (direct value overload)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Dynamiczne modyfikatory funkcji Composable:
    • Modifier.composed { ... } (uruchamia treść fabryczną podczas tworzenia; niezalecane ze względu na wydajność – zamiast tego używaj Modifier.Node w przypadku modyfikatorów niestandardowych)

Faza 2. Faza układu

Faza układu jest podzielona na 2 odrębne podetapy z osobnymi zakresami unieważnienia:

Krok 2A. Pomiar

Określa rozmiar (width, height) i ograniczenia. Odczyt stanu w tym miejscu wywołuje ponowny pomiar i ponowne umieszczenie:

  • Modifier.layout { measurable, constraints -> ... }: kod przed layout(w, h) jest wykonywany podczas pomiaru.

Krok 2B. Wywołania zwrotne dotyczące miejsca docelowego i układu

Określa pozycję współrzędnej (x, y). Odczyt stanu w blokach rozmieszczenia wywołuje tylko ponowne rozmieszczenie (pomijając pomiar i kompozycję):

  • Modifier.offset { IntOffset(x, y) } (przeciążenie lambda)
  • Modifier.absoluteOffset { IntOffset(x, y) } (przeciążenie lambda)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: kod wewnątrz bloku layout(w, h) { ... }.

Wywołania zwrotne obserwacji układu są również uruchamiane podczas lub po przejściu układu (unikaj zapisywania stanu odczytywanego w kompozycji w tych wywołaniach zwrotnych, ponieważ powoduje to zapisy wsteczne):

  • Modifier.onSizeChanged { intSize -> ... }: wywoływane po zakończeniu pomiaru układu, jeśli zmieniły się wymiary węzła.
  • Modifier.onPlaced { layoutCoordinates -> ... } i Modifier.onLayoutRectChanged { ... }: wywoływane po umieszczeniu w celu zgłoszenia współrzędnych lokalnych lub granic bez subskrybowania globalnych przebiegów układu okna.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: wywoływane po zakończeniu całego procesu układu okna, gdy dowolny węzeł zostanie przeniesiony. W miarę możliwości unikaj onGloballyPositioned. Do śledzenia widocznego obszaru lepiej używać Modifier.onVisibilityChanged, do lokalnych granic – Modifier.onPlaced lub Modifier.onLayoutRectChanged, a do żądania – requireLayoutCoordinates() wewnątrz Modifier.Node.

Faza 3. Faza rysowania

Te modyfikatory są wykonywane podczas rysowania obszaru roboczego. Odczyt stanu w tych blokach pomija zarówno tworzenie, jak i układ, i wykonuje tylko etap rysowania:

  • Modifier.graphicsLayer { ... }:
    • Właściwości zaktualizowane w funkcji lambda: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... }:
    • Rysuje polecenia obszaru roboczego za treścią kompozycyjną.
  • Modifier.drawWithContent { ... }:
    • Kontroluje kolejność rysowania za pomocą drawContent().
  • Modifier.drawWithCache { ... }:
    • Blok zewnętrzny jest uruchamiany, gdy zmienia się rozmiar lub układ, aby zapisać w pamięci podręcznej obiekty Path, Paint lub Brush. onDrawBehind lub onDrawWithContent jest uruchamiany przy każdym rysowaniu klatki.

Poza pętlą rekompozycji – modyfikatory obserwacji

Niektóre modyfikatory działają poza 3 fazami klatek, aby obsługiwać ułatwienia dostępu, dane wejściowe użytkownika i obserwacje cyklu życia.

Semantyka i ułatwienia dostępu

Przetwarza właściwości semantyczne na potrzeby usług ułatwień dostępu (TalkBack) i testowania:

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

Dane wejściowe, gesty i zdarzenia

Działa poza 3-fazowym potokiem renderowania klatek, odbierając zdarzenia ruchu z systemu operacyjnego i interakcje użytkownika:

  • 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 -> ... }: wywołanie zwrotne jest wywoływane, gdy widoczność elementu kompozycyjnego zmienia się po skonfigurowanym opóźnieniu, w ramach współprogramu.

Krótkie omówienie: faza wartości a faza lambda

Odczytanie wartości stanu w funkcji lambda odracza odczyt do późniejszego etapu, co pomija wcześniejsze etapy, gdy ten stan się zmienia:

Modyfikator / wzorzec Wartość bezpośrednia (struktura) Wariant Lambda (faza odroczona) Zmiana stanu
Przesunięcie Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Layout (Placement) (Skips Composition)
Kanał alfa / przezroczystość Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Rysowanie (pomija kompozycję i układ)
Obrót Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Rysowanie (pomija kompozycję i układ)
Skala Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Rysowanie (pomija kompozycję i układ)
Tłumaczenie Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Rysowanie (pomija kompozycję i układ)
Kolor tła Modifier.background(color) Modifier.drawBehind { drawRect(color) } Rysowanie (pomija kompozycję i układ)
Przewijanie / paralaksa Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Layout (Placement) (Skips Composition)

Mapowanie interfejsu Modifier.Node

W przypadku niestandardowych modyfikatorów korzystających z wysokowydajnego interfejsu API Modifier.Node fazy są mapowane bezpośrednio na interfejsy funkcji węzłów:

Etap Interfejs Modifier.Node Metody podstawowe
Układ (pomiar i umieszczanie) LayoutModifierNode measure(measurable, constraints)
Układ (współrzędne globalne) GlobalPositionAwareModifierNode (prefer requireLayoutCoordinates() on demand) onGloballyPositioned(coordinates)
Układ (miejsce docelowe) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Rysunek DrawModifierNode draw(ContentDrawScope)
Dane wejściowe / wskaźnik PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Semantyka SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Ostrość FocusEventModifierNode onFocusEvent(focusState)