Aufschlüsselung der Modifikatoren nach Phase

Jetpack Compose führt Modifikatoren in verschiedenen Phasen aus. In der folgenden Aufschlüsselung sehen Sie, zu welcher Phase gängige Modifikatoren gehören und wann ihre Argumente oder Lambdas ausgewertet werden.

Phase 1: Kompositionsphase

Diese Modifikatoren werten Argumente synchron im @Composable-Body aus. Jeder hier gelesene Status registriert eine Abhängigkeit mit dem Neustartbereich des Composable und löst bei einer Änderung eine vollständige Neuzusammensetzung aus.

  • Statische Dimensions- und Größenmodifikatoren:
    • 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) (in RowScope oder ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Statische Abstände und Einzüge:
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Visuelle Modifikatoren für direkte Werte:
    • Modifier.alpha(float) (liest den Status während der Erstellung)
    • Modifier.rotate(degrees) (liest den Status während der Erstellung)
    • Modifier.scale(scaleX, scaleY) (liest den Status während der Erstellung)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Modifikatoren für statische Positionen:
    • Modifier.offset(x = dp, y = dp) (Überlastung durch direkte Werte)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Dynamische Composable-Modifikatoren:
    • Modifier.composed { ... } (führt den Factory-Body während der Komposition aus; nicht empfohlen für die Leistung – verwende stattdessen Modifier.Node für benutzerdefinierte Modifikatoren)

Phase 2: Layoutphase

Die Layoutphase ist in zwei separate Unterschritte mit separaten Entwertungsumfängen unterteilt:

Schritt 2A: Messung

Bestimmt die Größe (width, height) und die Einschränkungen. Der hier gelesene Status löst eine erneute Messung und Neupositionierung aus:

  • Modifier.layout { measurable, constraints -> ... }: Code vor layout(w, h) wird während der Messung ausgeführt.

Schritt 2B: Callbacks für Platzierung und Layout

Bestimmt die (x, y)-Koordinate. Ein Status-Lesevorgang innerhalb von Platzierungsblöcken löst nur eine Neupositionierung aus (Messung und Komposition werden übersprungen):

  • Modifier.offset { IntOffset(x, y) } (Lambda-Überlastung)
  • Modifier.absoluteOffset { IntOffset(x, y) } (Lambda-Überlastung)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: Code im layout(w, h) { ... }-Block.

Callbacks für die Layoutbeobachtung werden auch während oder nach dem Layoutdurchlauf ausgeführt. Vermeiden Sie es, in diesen Callbacks in den Status zu schreiben, der in der Komposition gelesen wird, da dies zu Rückwärtsschreibvorgängen führt:

  • Modifier.onSizeChanged { intSize -> ... }: Wird aufgerufen, nachdem die Layoutmessung abgeschlossen ist, wenn sich die Abmessungen des Knotens geändert haben.
  • Modifier.onPlaced { layoutCoordinates -> ... } und Modifier.onLayoutRectChanged { ... }: Werden nach der Platzierung aufgerufen, um lokale Koordinaten oder Grenzen zu melden, ohne globale Fensterlayout-Durchgänge zu abonnieren.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: Wird aufgerufen, nachdem der gesamte Fensterlayout-Durchlauf abgeschlossen ist, wenn sich ein Knoten bewegt. Vermeiden Sie onGloballyPositioned, wenn möglich. Verwenden Sie stattdessen Modifier.onVisibilityChanged für das Viewport-Tracking, Modifier.onPlaced oder Modifier.onLayoutRectChanged für lokale Grenzen oder requireLayoutCoordinates() bei Bedarf innerhalb eines Modifier.Node.

Phase 3: Zeichenphase

Diese Modifikatoren werden während des Zeichnens auf dem Canvas ausgeführt. Wenn der Status innerhalb dieser Blöcke gelesen wird, werden sowohl die Komposition als auch das Layout übersprungen und nur der Zeichendurchlauf ausgeführt:

  • Modifier.graphicsLayer { ... }:
    • In Lambda aktualisierte Attribute: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... }:
    • Zeichnet Canvas-Befehle hinter dem kompositionierbaren Inhalt.
  • Modifier.drawWithContent { ... }:
    • Steuert die Zeichenreihenfolge mit drawContent().
  • Modifier.drawWithCache { ... }:
    • Der äußere Block wird bei Größen- oder Layoutänderungen ausgeführt, um Path-, Paint- oder Brush-Objekte im Cache zu speichern. onDrawBehind oder onDrawWithContent wird bei jedem Frame-Zeichnen ausgeführt.

Außerhalb der Neuzusammensetzungsschleife – Beobachtungsmodifikatoren

Einige Modifikatoren werden außerhalb der drei Frame-Phasen ausgeführt, um Bedienungshilfen, Nutzereingaben und Lebenszyklusbeobachtungen zu verarbeiten.

Semantik und Bedienungshilfen

Verarbeitet semantische Eigenschaften für Bedienungshilfen (TalkBack) und Tests:

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

Eingabe, Gesten und Ereignisse

Arbeitet außerhalb der dreiphasigen Frame-Rendering-Pipeline und empfängt Betriebssystem-Bewegungsereignisse und Nutzerinteraktionen:

  • 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 -> ... }: Der Callback wird aufgerufen, wenn sich die Sichtbarkeit einer zusammensetzbaren Funktion nach der konfigurierten Verzögerung in einer Koroutine ändert.

Kurzreferenz: Wert- und Lambda-Phase

Wenn ein Zustandswert in einem Lambda gelesen wird, wird der Lesevorgang auf eine spätere Phase verschoben. Dadurch werden frühere Phasen übersprungen, wenn sich dieser Zustand ändert:

Modifikator / Muster Direkter Wert (Zusammensetzung) Lambda-Variante (verzögerte Phase) Wenn sich der Status ändert
Offset Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Layout (Placement) (überspringt die Komposition)
Alpha / Deckkraft Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Zeichnen (Komposition und Layout werden übersprungen)
Rotation Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Zeichnen (Komposition und Layout werden übersprungen)
Scale Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Zeichnen (Komposition und Layout werden übersprungen)
Translation Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Zeichnen (Komposition und Layout werden übersprungen)
Hintergrundfarbe Modifier.background(color) Modifier.drawBehind { drawRect(color) } Zeichnen (Komposition und Layout werden übersprungen)
Scrollen / Parallaxe Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Layout (Placement) (überspringt die Komposition)

Zuordnung der Modifier.Node-Schnittstelle

Bei benutzerdefinierten Modifikatoren, die die leistungsstarke Modifier.Node API verwenden, werden Phasen direkt den Schnittstellen für Knotenfunktionen zugeordnet:

Phase Modifier.Node-Schnittstelle Kernmethoden
Layout (Messen und platzieren) LayoutModifierNode measure(measurable, constraints)
Layout (globale Koordinaten) GlobalPositionAwareModifierNode (requireLayoutCoordinates() on Demand bevorzugen) onGloballyPositioned(coordinates)
Layout (Placement) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Zeichnung DrawModifierNode draw(ContentDrawScope)
Eingabe / Pointer PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Semantik SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Fokus FocusEventModifierNode onFocusEvent(focusState)