Scrollen

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

Scroll-Modifikatoren

Die Modifikatoren verticalScroll und horizontalScroll sind die einfachste Möglichkeit, dem Nutzer das Scrollen eines Elements zu ermöglichen, wenn die Grenzen des Inhalts größer sind als die maximalen Größenbeschränkungen. Mit den Modifikatoren verticalScroll und horizontalScroll müssen Sie die Inhalte nicht übersetzen oder versetzen.

@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 Scrollgesten reagiert.

Mit ScrollState können Sie die Scrollposition ändern oder den aktuellen Status abrufen. Verwenden Sie zum Erstellen mit Standardparametern rememberScrollState().

@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 Modifikator scrollableArea ist ein grundlegender Baustein zum Erstellen benutzerdefinierter scrollbarer Container. Sie bietet eine Abstraktion auf höherer Ebene für den Modifikator scrollable und verarbeitet häufige Anforderungen wie die Interpretation von Gestendeltas, das Zuschneiden von Inhalten und Overscroll-Effekte.

scrollableArea wird für benutzerdefinierte Implementierungen verwendet. Im Allgemeinen sollten Sie jedoch vorgefertigte Lösungen wie verticalScroll, horizontalScroll oder Composables wie LazyColumn für standardmäßige Scrolllisten bevorzugen. Diese Komponenten auf höherer Ebene 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 in der Art und Weise, wie sie Scrollgesten von Nutzern interpretieren:

• scrollable (Rohdelta): Das Delta spiegelt die physische Bewegung der Eingabe des Nutzers (z.B. das Ziehen des Mauszeigers) auf dem Bildschirm wider.
• scrollableArea (inhaltsorientiertes Delta): Das delta wird semantisch invertiert, um die ausgewählte Änderung der Scrollposition darzustellen. Dadurch scheint sich der Inhalt entsprechend der Geste des Nutzers zu bewegen, was in der Regel das Gegenteil der Zeigerbewegung ist.

scrollable gibt an, wie sich der Zeiger bewegt hat, während scrollableArea diese Zeigerbewegung in die Bewegung der Inhalte in einer typischen scrollbaren Ansicht umwandelt. Diese Inversion ist der Grund, warum scrollableArea bei der Implementierung eines standardmäßigen scrollbaren Containers natürlicher wirkt.

In der folgenden Tabelle sind die Deltazeichen für häufige Szenarien zusammengefasst:

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

(*) Hinweis zum scrollableArea-Deltazeichen: Das Vorzeichen des Deltas von scrollableArea ist nicht nur eine einfache Inversion. 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.

Neben der Invertierung des Scroll-Deltas beschneidet scrollableArea den Inhalt auch auf die Grenzen des Layouts und rendert Overscroll-Effekte. Standardmäßig wird der Effekt von LocalOverscrollFactory verwendet. Sie können diese Funktion anpassen oder deaktivieren, indem Sie die Überladung scrollableArea verwenden, die einen OverscrollEffect-Parameter akzeptiert.

Wann sollte der Modifikator scrollableArea verwendet werden?

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

• Benutzerdefinierte Layoutlogik: Wenn sich die Anordnung von Elementen dynamisch basierend auf der Scrollposition ändert.
• Einzigartige visuelle Effekte: Anwenden von Transformationen, Skalierungen oder anderen Effekten auf Kinder beim Scrollen.
• Direkte Steuerung: Sie benötigen eine detaillierte Steuerung der Scrollmechanismen, die über die von verticalScroll oder Lazy-Layouts bereitgestellten Möglichkeiten hinausgeht.

Benutzerdefinierte radähnliche Listen mit scrollableArea erstellen

Im folgenden Beispiel wird gezeigt, wie Sie mit scrollableArea eine benutzerdefinierte vertikale Liste erstellen, in der die Elemente kleiner werden, je weiter sie sich vom Mittelpunkt entfernen. So 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 Modifier auf niedriger Ebene, der Eingabe-Gesten für das Scrollen auf niedriger Ebene 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 clips its content to its bounds, renders overscroll, and adjusts the direction of scroll gestures to verify that the content moves with the user's gestures.

Der Modifier scrollable unterscheidet sich von den Scroll-Modifizierern dadurch, dass scrollable die Scroll-Gesten erkennt und die Deltas erfasst, aber den Inhalt nicht automatisch verschiebt. Stattdessen wird sie über ScrollableState an den Nutzer delegiert, was für die korrekte Funktion dieses Modifikators erforderlich ist.

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

Hinweis :Der Modifikator scrollable wirkt sich nicht auf das Layout des Elements aus, auf das er angewendet wird. Das bedeutet, dass alle Änderungen am Elementlayout oder an den untergeordneten Elementen über das von ScrollableState bereitgestellte Delta erfolgen müssen. Außerdem ist es wichtig zu beachten, dass scrollable keine Meinung zu Layouts für Kinder hat. Das bedeutet, dass die Kinder nicht gemessen werden müssen, um das Scrolling-Delta zu übertragen.

Im folgenden Snippet werden die Gesten erkannt und ein numerischer Wert für einen Offset angezeigt, es werden jedoch 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 das Drücken des Fingers erkennt und den numerischen Wert für die Position des Fingers anzeigt.