Scroll-Modifikatoren

Hinweis: Wenn Sie eine Liste von Elementen anzeigen möchten, sollten Sie LazyColumn und LazyRow anstelle dieser APIs verwenden. LazyColumn und LazyRow bieten Scrollfunktionen und sind viel effizienter als der Scroll-Modifikator, da sie die Elemente nur bei Bedarf zusammensetzen. Weitere Informationen findest du in der Dokumentation zu Listen und Rastern.

Die Modifikatoren verticalScroll und horizontalScroll bieten die einfachste Möglichkeit, Nutzern das Scrollen in einem Element zu ermöglichen, wenn die Grenzen des Inhalts größer als die maximalen Größenbeschränkungen sind. Mit den Modifikatoren verticalScroll und horizontalScroll müssen Sie den Inhalt nicht übersetzen oder verschieben.

@Composable
private fun ScrollBoxes() {
    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .verticalScroll(rememberScrollState())
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}
GesturesSnippets.kt

Abbildung 1. Eine einfache vertikale Liste, die auf Scroll-Gesten reagiert.

Mit ScrollState können Sie die Scrollposition ändern oder den aktuellen Status abrufen. Verwenden Sie rememberScrollState(), um sie mit Standardparametern zu erstellen.

@Composable
private fun ScrollBoxesSmooth() {
    // Smoothly scroll 100px on first composition
    val state = rememberScrollState()
    LaunchedEffect(Unit) { state.animateScrollTo(100) }

    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .padding(horizontal = 8.dp)
            .verticalScroll(state)
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}
GesturesSnippets.kt

Modifikator für scrollbaren Bereich

Der scrollableArea-Modifikator ist ein grundlegender Baustein zum Erstellen benutzerdefinierter scrollbarer Container. Er bietet eine übergeordnete Abstraktion des Modifikators scrollable und verarbeitet gängige Anforderungen wie die Interpretation von Gesten-Deltas, das Abschneiden von Inhalten und Overscroll-Effekte.

scrollableArea wird für benutzerdefinierte Implementierungen verwendet. Für Standard-Scrolllisten sollten Sie jedoch im Allgemeinen vorgefertigte Lösungen wie verticalScroll, horizontalScroll oder Composables wie LazyColumn bevorzugen. Diese übergeordneten Komponenten sind für gängige Anwendungsfälle einfacher und werden selbst mit scrollableArea erstellt.

Unterschied zwischen den Modifikatoren scrollableArea und scrollable

Der Hauptunterschied zwischen scrollableArea und scrollable liegt darin, wie sie die Scroll-Gesten des Nutzers interpretieren:

• scrollable (Roh-Delta): Das Delta spiegelt direkt die physische Bewegung der Nutzereingabe (z.B. Ziehen des Mauszeigers) auf dem Bildschirm wider.
• scrollableArea (Inhaltsorientiertes Delta): Der delta wird semantisch invertiert, um die ausgewählte Änderung der Scrollposition darzustellen, sodass der Inhalt sich mit der Geste des Nutzers zu bewegen scheint. Dies ist normalerweise das Gegenteil der Zeigerbewegung.

Stellt euch das so vor: scrollable gibt an, wie sich der Zeiger bewegt hat, während scrollableArea diese Zeigerbewegung in die Bewegung des Inhalts innerhalb einer typischen scrollbaren Ansicht übersetzt. Diese Umkehrung ist der Grund, warum sich scrollableArea bei der Implementierung eines standardmäßigen scrollbaren Containers natürlicher anfühlt.

In der folgenden Tabelle sind die Delta-Zeichen für gängige Szenarien zusammengefasst:

Nutzergeste	Delta, das dispatchRawDelta von scrollable gemeldet wurde	Delta, das dispatchRawDelta von scrollableArea gemeldet wurde*
Mauszeiger bewegt sich NACH OBEN	Negative	Positiv
Der Mauszeiger bewegt sich NACH UNTEN.	Positiv	Negative
Mauszeiger bewegt sich nach LINKS	Negative	Positiv (Negativ für RTL)
Mauszeiger bewegt sich nach RECHTS	Positiv	Negativ (Positiv für RTL)

(*) Hinweis zum Deltazeichen von scrollableArea: Das Vorzeichen des Deltas von scrollableArea ist nicht einfach nur eine Umkehrung. Dabei werden folgende Faktoren berücksichtigt:

1. Ausrichtung: Vertikal oder horizontal.
2. LayoutDirection: LTR oder RTL (besonders wichtig für horizontales Scrollen).
3. reverseScrolling-Flag: Gibt an, ob die Scrollrichtung umgekehrt ist.

scrollableArea invertiert nicht nur das Scroll-Delta, sondern schneidet auch den Inhalt auf die Grenzen des Layouts zu und übernimmt das Rendering von Overscroll-Effekten. Standardmäßig wird der von LocalOverscrollFactory bereitgestellte Effekt verwendet. Sie können dies anpassen oder deaktivieren, indem Sie die Überladung scrollableArea verwenden, die einen OverscrollEffect-Parameter akzeptiert.

Wann der Modifikator scrollableArea verwendet werden sollte

Verwenden Sie den Modifikator scrollableArea, wenn Sie eine benutzerdefinierte Scrollkomponente erstellen müssen, die nicht ausreichend durch die Modifikatoren horizontalScroll oder verticalScroll oder Lazy-Layouts abgedeckt wird. Dazu gehören häufig Fälle mit:

• Benutzerdefinierte Layoutlogik: Wenn sich die Anordnung der Elemente dynamisch je nach Scrollposition ändert.
• Einzigartige visuelle Effekte: Transformationen, Skalierungen oder andere Effekte auf untergeordnete Elemente anwenden, während der Nutzer scrollt.
• Direkte Steuerung: Sie benötigen eine detaillierte Steuerung der Scrollmechanismen, die über die Möglichkeiten von verticalScroll oder Lazy-Layouts hinausgeht.

Benutzerdefinierte radähnliche Listen mit scrollableArea erstellen

Im folgenden Beispiel wird gezeigt, wie Sie mit scrollableArea eine benutzerdefinierte vertikale Liste erstellen, in der Elemente verkleinert werden, wenn sie sich von der Mitte entfernen. Dadurch entsteht ein „radähnlicher“ visueller Effekt. Diese Art von scrollabhängiger Transformation ist ein perfekter Anwendungsfall für scrollableArea.

Abbildung 2. Eine benutzerdefinierte vertikale Liste mit scrollableArea.

@Composable
private fun ScrollableAreaSample() {
    // ...
    Layout(
        modifier =
            Modifier
                .size(150.dp)
                .scrollableArea(scrollState, Orientation.Vertical)
                .background(Color.LightGray),
        // ...
    ) { measurables, constraints ->
        // ...
        // Update the maximum scroll value to not scroll beyond limits and stop when scroll
        // reaches the end.
        scrollState.maxValue = (totalHeight - viewportHeight).coerceAtLeast(0)

        // Position the children within the layout.
        layout(constraints.maxWidth, viewportHeight) {
            // The current vertical scroll position, in pixels.
            val scrollY = scrollState.value
            val viewportCenterY = scrollY + viewportHeight / 2

            var placeableLayoutPositionY = 0
            placeables.forEach { placeable ->
                // This sample applies a scaling effect to items based on their distance
                // from the center, creating a wheel-like effect.
                // ...
                // Place the item horizontally centered with a layer transformation for
                // scaling to achieve wheel-like effect.
                placeable.placeRelativeWithLayer(
                    x = constraints.maxWidth / 2 - placeable.width / 2,
                    // Offset y by the scroll position to make placeable visible in the viewport.
                    y = placeableLayoutPositionY - scrollY,
                ) {
                    scaleX = scaleFactor
                    scaleY = scaleFactor
                }
                // Move to the next item's vertical position.
                placeableLayoutPositionY += placeable.height
            }
        }
    }
}
// ...
GesturesSnippets.kt

Scrollbarer Modifikator

Hinweis: scrollable ist ein Low-Level-Modifikator, der Low-Level-Scroll-Eingabegesten verarbeitet, ohne andere Verhaltensweisen, die häufig für scrollbare Container verwendet werden. Informationen zum Erstellen scrollbarer Container finden Sie unter androidx.compose.foundation.scrollableArea. scrollableArea schneidet den Inhalt auf die Grenzen zu, rendert Overscroll und passt die Richtung der Scroll-Gesten an, um zu prüfen, ob sich der Inhalt mit den Gesten des Nutzers bewegt.

Der Modifikator scrollable unterscheidet sich von den Scroll-Modifikatoren dadurch, dass scrollable die Scroll-Gesten erkennt und die Deltas erfasst, aber den Inhalt nicht automatisch verschiebt. Stattdessen wird dies über ScrollableState an den Nutzer delegiert, was erforderlich ist, damit dieser Modifikator ordnungsgemäß funktioniert.

Beim Erstellen von ScrollableState müssen Sie eine consumeScrollDelta-Funktion angeben, die bei jedem Scrollschritt (durch Gesteneingabe, optimiertes Scrollen oder schnelles Scrollen) mit dem Delta in Pixeln aufgerufen wird. Diese Funktion muss die verbrauchte Scroll-Distanz zurückgeben, damit das Ereignis ordnungsgemäß weitergegeben wird, wenn verschachtelte Elemente mit dem Modifikator scrollable vorhanden sind.

Hinweis: Der scrollable-Modifikator hat keinen Einfluss auf das Layout des Elements, auf das er angewendet wird. Das bedeutet, dass alle Änderungen am Elementlayout oder an den untergeordneten Elementen über das von ScrollableState bereitgestellte Delta verarbeitet werden müssen. Außerdem ist es wichtig zu beachten, dass scrollable keine Meinung zu den Layouts der untergeordneten Elemente hat. Das bedeutet, dass die untergeordneten Elemente nicht gemessen werden müssen, um das Scroll-Delta weiterzugeben.

Im folgenden Snippet werden die Gesten erkannt und ein numerischer Wert für einen Versatz angezeigt, aber es werden keine Elemente versetzt:

@Composable
private fun ScrollableSample() {
    // actual composable state
    var offset by remember { mutableFloatStateOf(0f) }
    Box(
        Modifier
            .size(150.dp)
            .scrollable(
                orientation = Orientation.Vertical,
                // Scrollable state: describes how to consume
                // scrolling delta and update offset
                state = rememberScrollableState { delta ->
                    offset += delta
                    delta
                }
            )
            .background(Color.LightGray),
        contentAlignment = Alignment.Center
    ) {
        Text(offset.toString())
    }
}
GesturesSnippets.kt

Abbildung 3: Ein UI-Element, das den Fingerdruck erkennt und den numerischen Wert für die Position des Fingers anzeigt.