Faire défiler

Modificateurs Scroll

Les modificateurs verticalScroll et horizontalScroll sont la solution la plus simple pour autoriser l'utilisateur à faire défiler un élément lorsque les limites de son contenu dépassent les contraintes de taille maximales. Avec les modificateurs verticalScroll et horizontalScroll, vous n'avez pas besoin de décaler le contenu ni d'effectuer une translation.

@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

ScrollState vous permet de modifier la position de défilement ou d'obtenir son état actuel. Pour le créer avec des paramètres par défaut, utilisez 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

Modificateur Scrollable

La scrollable diffère des modificateurs de défilement dans la mesure où scrollable détecte la gestes de défilement et capture les deltas, mais ne décale pas son contenu automatiquement. Celui-ci est délégué à l'utilisateur via ScrollableState , nécessaire au bon fonctionnement de ce modificateur.

Lorsque vous créez ScrollableState, vous devez fournir un consumeScrollDelta. qui sera appelée à chaque étape de défilement (par saisie gestuelle, (défilement ou glissement d'un geste vif) avec le delta en pixels. Cette fonction doit renvoyer la la distance de défilement consommée, pour garantir que l'événement propagée dans les cas où des éléments imbriqués ont le scrollable modificateur.

L'extrait de code suivant détecte les gestes et affiche une valeur numérique correspondant à un décalage, mais ne décale aucun élément :

@Composable
private fun ScrollableSample() {
    // actual composable state
    var offset by remember { mutableStateOf(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

Défilement imbriqué

Le défilement imbriqué est un système dans lequel plusieurs composants de défilement contiennent interagissent entre eux en réagissant à un seul geste de défilement. communiquer leurs deltas de défilement (modifications).

Le système de défilement imbriqué permet de coordonner entre les composants qui sont les éléments à faire défiler et les liens hiérarchiques (le plus souvent en partageant le même parent). Ce système associe les conteneurs à faire défiler et permet d'interagir avec le défilement deltas qui sont propagés et partagés entre.

Compose propose plusieurs façons de gérer le défilement imbriqué entre les composables. Un exemple typique de défilement imbriqué est une liste à l'intérieur d'une autre liste, et un bouton plus une demande complexe est une réplication barre d'outils.

Défilement imbriqué automatique

Le défilement imbriqué simple ne nécessite aucune action de votre part. Les gestes qui déclenchent une action de défilement sont automatiquement propagés depuis les enfants vers les parents. Ainsi, lorsque l'enfant ne peut plus faire défiler la page, le geste est géré par son élément parent.

Le défilement imbriqué automatique est pris en charge et fourni immédiatement par certains des Composants et modificateurs de Compose: verticalScroll, horizontalScroll, scrollable, Lazy API et TextField. Cela signifie que lorsque l'utilisateur fait défiler une page interne enfant des composants imbriqués, les modificateurs précédents propagent le défilement deltas aux parents qui prennent en charge le défilement imbriqué.

L'exemple suivant montre des éléments avec verticalScroll un modificateur qui leur est appliqué dans un conteneur qui comporte également un élément verticalScroll. ou modificateur qui lui est appliqué.

@Composable
private fun AutomaticNestedScroll() {
    val gradient = Brush.verticalGradient(0f to Color.Gray, 1000f to Color.White)
    Box(
        modifier = Modifier
            .background(Color.LightGray)
            .verticalScroll(rememberScrollState())
            .padding(32.dp)
    ) {
        Column {
            repeat(6) {
                Box(
                    modifier = Modifier
                        .height(128.dp)
                        .verticalScroll(rememberScrollState())
                ) {
                    Text(
                        "Scroll here",
                        modifier = Modifier
                            .border(12.dp, Color.DarkGray)
                            .background(brush = gradient)
                            .padding(24.dp)
                            .height(150.dp)
                    )
                }
            }
        }
    }
}
GesturesSnippets.kt

Utiliser le modificateur nestedScroll

Si vous devez créer un défilement coordonné plus complexe entre plusieurs éléments, le modificateur nestedScroll vous offre plus de flexibilité en définissant une hiérarchie de défilements imbriqués. En tant que mentionné dans la section précédente, certains composants intègrent des fonctionnalités de l'assistance. Toutefois, pour les composables qu'il n'est pas possible de faire défiler automatiquement, comme Box ou Column, les deltas de défilement sur ces composants ne se propagent pas dans le de défilement imbriqué et les deltas n'atteindront pas NestedScrollConnection ni le composant parent. Pour résoudre ce problème, vous pouvez utiliser nestedScroll pour transmettre ces la prise en charge d'autres composants, y compris les composants personnalisés.

Cycle de défilement imbriqué

Le cycle de défilement imbriqué est le flux de deltas de défilement qui sont répartis vers le haut et vers le bas. l'arborescence de l'arborescence à travers tous les composants (ou nœuds) qui font partie un système de défilement, par exemple à l'aide de composants et de modificateurs à défilement ; ou nestedScroll

Phases du cycle de défilement imbriqué

Lorsqu'un événement déclencheur (un geste, par exemple) est détecté par un élément , avant même que l'action de défilement ne soit déclenchée, le code les deltas sont envoyés au système de défilement imbriqué et passent par trois phases: le prédéfilement, la consommation de nœuds et le post-défilement.

Au cours de la première phase de prédéfilement, le composant qui a reçu l'événement déclencheur les deltas acheminent ces événements vers le sommet le plus élevé, parent. Les événements delta s'affichent alors vers le bas, ce qui signifie que les deltas sont se propage du parent le plus proche de la racine vers l'enfant qui a démarré le et le cycle de défilement imbriqué.

Cela donne aux parents de défilement imbriqués (composables utilisant nestedScroll ou modificateurs à défilement), la possibilité d'effectuer une action avec le delta avant la le nœud lui-même peut le consommer.

Dans la phase de consommation de nœuds, le nœud lui-même utilise le delta qui n'a pas été utilisés par ses parents. C'est à ce moment-là que le mouvement de défilement est réellement terminé et qu'il visible.

Pendant cette phase, l'enfant peut choisir de consommer tout ou partie des faire défiler. Les éléments restants seront renvoyés vers le haut pour passer par la phase post-défilement.

Enfin, dans la phase post-défilement, tout ce que le nœud lui-même ne consomme pas sont à nouveau envoyés à ses ancêtres pour utilisation.

La phase post-défilement fonctionne de la même manière que la phase de prédéfilement, où n'importe quelle des parents peuvent choisir de consommer ou non.

Comme pour le défilement, lorsqu'un geste de glissement se termine, l'intention de l'utilisateur peut être est traduite en une vitesse qui sert à faire glisser l'écran (défilement à l'aide d'une animation) conteneur déroulant. Le glissement d'un geste vif fait également partie du cycle de défilement imbriqué, et les vitesses générées par l'événement de glissement passent par des phases similaires: pré-glissement, la consommation des nœuds et le post-glissement. Notez que l'animation de glissement n'est associée à l'aide d'un geste tactile et qui ne sera pas déclenché par d'autres événements tels que l'accessibilité ou le défilement matériel.

Participer au cycle de défilement imbriqué

La participation au cycle implique d’intercepter, de consommer et de signaler la consommation de deltas le long de la hiérarchie. Compose fournit un ensemble d'outils influencent le fonctionnement du système de défilement imbriqué et la façon d'interagir directement par exemple, lorsque vous devez effectuer quelque chose avec les deltas de défilement avant un composant déroulant commence même à faire défiler.

Si le cycle de défilement imbriqué est un système agissant sur une chaîne de nœuds, nestedScroll est un moyen d'intercepter et d'insérer ces modifications. influencer les données (deltas de défilement) qui se propagent dans la chaîne. Ce peut être placé n'importe où dans la hiérarchie et communique avec des instances du modificateur de défilement imbriqué dans l'arborescence pour pouvoir partager des informations cette chaîne. Les éléments de base de ce modificateur sont NestedScrollConnection et NestedScrollDispatcher.

NestedScrollConnection permet de répondre aux phases du cycle de défilement imbriqué et influence le système de défilement imbriqué. Il est composé de quatre méthodes de rappel, chacune représentant l'une des phases de consommation (pré/post-défilement et pré/post-glissement) :

val nestedScrollConnection = object : NestedScrollConnection {
    override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
        println("Received onPreScroll callback.")
        return Offset.Zero
    }

    override fun onPostScroll(
        consumed: Offset,
        available: Offset,
        source: NestedScrollSource
    ): Offset {
        println("Received onPostScroll callback.")
        return Offset.Zero
    }
}
GesturesSnippets.kt

Chaque rappel fournit également des informations sur le delta en cours de propagation: Delta de available pour cette phase particulière et delta de consumed consommé dans des phases précédentes. Si vous voulez arrêter de propager des deltas à un moment donné vous pouvez utiliser la connexion de défilement imbriqué pour ce faire:

val disabledNestedScrollConnection = remember {
    object : NestedScrollConnection {
        override fun onPostScroll(
            consumed: Offset,
            available: Offset,
            source: NestedScrollSource
        ): Offset {
            return if (source == NestedScrollSource.SideEffect) {
                available
            } else {
                Offset.Zero
            }
        }
    }
}
GesturesSnippets.kt

Tous les rappels fournissent des informations sur le NestedScrollSource de mots clés.

NestedScrollDispatcher initialise le cycle de défilement imbriqué. Utiliser un coordinateur et appeler ses méthodes déclenche le cycle. Les conteneurs à défilement s'accompagnent d'un coordinateur intégré qui envoie deltas capturés lors des gestes dans le système. C'est pourquoi la plupart des cas d'utilisation la personnalisation du défilement imbriqué implique l'utilisation de NestedScrollConnection à la place d'un coordinateur, pour réagir aux deltas existants plutôt que d'en envoyer de nouveaux. Voir NestedScrollDispatcherSample pour d'autres utilisations.

Interopérabilité du défilement imbriqué

Lorsque vous essayez d'imbriquer des éléments View à défilement dans des composables à défilement, ou l'inverse, vous pourriez rencontrer des problèmes. Les plus perceptibles se produit lorsque vous faites défiler l'élément enfant et que vous atteignez les limites de début ou de fin et que au parent de reprendre le défilement. Toutefois, ce comportement attendu est soit risque de ne pas se produire ou de ne pas fonctionner comme prévu.

Ce problème est dû aux attentes que les développeurs fondent sur les composables à défilement. Les composables à défilement disposent d'une règle "nested-scroll-by-default", qui signifie que tout conteneur à défilement doit participer à la chaîne de défilement imbriquée, à la fois en tant que parent via NestedScrollConnection et en tant qu'enfant via NestedScrollDispatcher. Une fois sa limite atteinte, l'enfant doit déclencher un défilement imbriqué pour l'élément parent. Par exemple, cette règle permet aux composants Pager et LazyRow de Compose de fonctionner correctement ensemble. Toutefois, lorsque l'interopérabilité du défilement est assurée par ViewPager2 ou RecyclerView, comme ces composants n'implémentent pas NestedScrollingParent3, le défilement continu de l'enfant vers le parent est impossible.

Pour permettre l'interopérabilité du défilement imbriqué entre des éléments View à défilement et des composables à défilement, imbriqués dans les deux sens, vous pouvez utiliser l'API dédiée. Cela permettra de limiter ces problèmes dans les scénarios suivants.

Un View parent coopératif contenant un ComposeView enfant

Un View parent coopératif est déjà un élément qui implémente déjà NestedScrollingParent3 et est donc capable de recevoir des deltas de défilement d'un composable enfant. Dans ce cas, ComposeView agirait en tant qu'enfant. devez implémenter (indirectement) NestedScrollingChild3 Un exemple de parent coopérant est androidx.coordinatorlayout.widget.CoordinatorLayout

Pour assurer l'interopérabilité du défilement imbriqué entre des conteneurs parents View à défilement et des composables enfants imbriqués à défilement, vous pouvez utiliser rememberNestedScrollInteropConnection().

rememberNestedScrollInteropConnection() autorise et mémorise le NestedScrollConnection qui permet l'interopérabilité du défilement imbriqué entre un View parent implémentant NestedScrollingParent3 et un enfant Compose. Il doit être utilisé conjointement avec un modificateur nestedScroll. Étant donné que le défilement imbriqué est activé par défaut dans Compose, vous pouvez vous pouvez utiliser cette connexion pour activer le défilement imbriqué du côté View et ajouter la logique Glue nécessaire entre Views et les composables.

Les cas d'utilisation suivants sont fréquent : CoordinatorLayout, CollapsingToolbarLayout et un composable enfant, présenté dans cet exemple:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.google.android.material.appbar.AppBarLayout
        android:id="@+id/app_bar"
        android:layout_width="match_parent"
        android:layout_height="100dp"
        android:fitsSystemWindows="true">

        <com.google.android.material.appbar.CollapsingToolbarLayout
            android:id="@+id/collapsing_toolbar_layout"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:fitsSystemWindows="true"
            app:layout_scrollFlags="scroll|exitUntilCollapsed">

            <!--...-->

        </com.google.android.material.appbar.CollapsingToolbarLayout>

    </com.google.android.material.appbar.AppBarLayout>

    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/compose_view"
        app:layout_behavior="@string/appbar_scrolling_view_behavior"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</androidx.coordinatorlayout.widget.CoordinatorLayout>
touchinput_gestures_nested_scroll_interop.xml

Dans votre activité ou fragment, vous devez configurer votre composable enfant et le composant obligatoire NestedScrollConnection:

open class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        findViewById<ComposeView>(R.id.compose_view).apply {
            setContent {
                val nestedScrollInterop = rememberNestedScrollInteropConnection()
                // Add the nested scroll connection to your top level @Composable element
                // using the nestedScroll modifier.
                LazyColumn(modifier = Modifier.nestedScroll(nestedScrollInterop)) {
                    items(20) { item ->
                        Box(
                            modifier = Modifier
                                .padding(16.dp)
                                .height(56.dp)
                                .fillMaxWidth()
                                .background(Color.Gray),
                            contentAlignment = Alignment.Center
                        ) {
                            Text(item.toString())
                        }
                    }
                }
            }
        }
    }
}
GesturesSnippets.kt

Un composable parent contenant un AndroidView enfant

Ce scénario concerne l'implémentation de l'API d'interopérabilité du défilement imbriqué du côté de Compose, lorsqu'un composable parent contient un AndroidView enfant. Le composant AndroidView implémente NestedScrollDispatcher, car il agit en tant qu'enfant d'un parent à défilement Compose, et aussi NestedScrollingParent3, car il agit en tant que parent d'un enfant à défilement View. Le parent Compose va pouvoir recevoir des deltas de défilement imbriqué d'un enfant à défilement imbriqué View

L'exemple suivant montre comment assurer l'interopérabilité du défilement imbriqué dans ce dans ce scénario, ainsi qu'une barre d'outils pouvant être réduite Compose:

@Composable
private fun NestedScrollInteropComposeParentWithAndroidChildExample() {
    val toolbarHeightPx = with(LocalDensity.current) { ToolbarHeight.roundToPx().toFloat() }
    val toolbarOffsetHeightPx = remember { mutableStateOf(0f) }

    // Sets up the nested scroll connection between the Box composable parent
    // and the child AndroidView containing the RecyclerView
    val nestedScrollConnection = remember {
        object : NestedScrollConnection {
            override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
                // Updates the toolbar offset based on the scroll to enable
                // collapsible behaviour
                val delta = available.y
                val newOffset = toolbarOffsetHeightPx.value + delta
                toolbarOffsetHeightPx.value = newOffset.coerceIn(-toolbarHeightPx, 0f)
                return Offset.Zero
            }
        }
    }

    Box(
        Modifier
            .fillMaxSize()
            .nestedScroll(nestedScrollConnection)
    ) {
        TopAppBar(
            modifier = Modifier
                .height(ToolbarHeight)
                .offset { IntOffset(x = 0, y = toolbarOffsetHeightPx.value.roundToInt()) }
        )

        AndroidView(
            { context ->
                LayoutInflater.from(context)
                    .inflate(R.layout.view_in_compose_nested_scroll_interop, null).apply {
                        with(findViewById<RecyclerView>(R.id.main_list)) {
                            layoutManager = LinearLayoutManager(context, VERTICAL, false)
                            adapter = NestedScrollInteropAdapter()
                        }
                    }.also {
                        // Nested scrolling interop is enabled when
                        // nested scroll is enabled for the root View
                        ViewCompat.setNestedScrollingEnabled(it, true)
                    }
            },
            // ...
        )
    }
}

private class NestedScrollInteropAdapter :
    Adapter<NestedScrollInteropAdapter.NestedScrollInteropViewHolder>() {
    val items = (1..10).map { it.toString() }

    override fun onCreateViewHolder(
        parent: ViewGroup,
        viewType: Int
    ): NestedScrollInteropViewHolder {
        return NestedScrollInteropViewHolder(
            LayoutInflater.from(parent.context)
                .inflate(R.layout.list_item, parent, false)
        )
    }

    override fun onBindViewHolder(holder: NestedScrollInteropViewHolder, position: Int) {
        // ...
    }

    class NestedScrollInteropViewHolder(view: View) : ViewHolder(view) {
        fun bind(item: String) {
            // ...
        }
    }
    // ...
}

L'exemple suivant montre comment utiliser l'API avec un modificateur scrollable :

@Composable
fun ViewInComposeNestedScrollInteropExample() {
    Box(
        Modifier
            .fillMaxSize()
            .scrollable(rememberScrollableState {
                // View component deltas should be reflected in Compose
                // components that participate in nested scrolling
                it
            }, Orientation.Vertical)
    ) {
        AndroidView(
            { context ->
                LayoutInflater.from(context)
                    .inflate(android.R.layout.list_item, null)
                    .apply {
                        // Nested scrolling interop is enabled when
                        // nested scroll is enabled for the root View
                        ViewCompat.setNestedScrollingEnabled(this, true)
                    }
            }
        )
    }
}

Enfin, l'exemple suivant montre comment obtenir un comportement de type "faire glisser pour fermer la vue" en utilisant l'API d'interopérabilité du défilement imbriqué avec BottomSheetDialogFragment :

class BottomSheetFragment : BottomSheetDialogFragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        val rootView: View = inflater.inflate(R.layout.fragment_bottom_sheet, container, false)

        rootView.findViewById<ComposeView>(R.id.compose_view).apply {
            setContent {
                val nestedScrollInterop = rememberNestedScrollInteropConnection()
                LazyColumn(
                    Modifier
                        .nestedScroll(nestedScrollInterop)
                        .fillMaxSize()
                ) {
                    item {
                        Text(text = "Bottom sheet title")
                    }
                    items(10) {
                        Text(
                            text = "List item number $it",
                            modifier = Modifier.fillMaxWidth()
                        )
                    }
                }
            }
            return rootView
        }
    }
}

Notez que rememberNestedScrollInteropConnection() installera NestedScrollConnection dans l'élément auquel vous l'associez. NestedScrollConnection assure la transmission des deltas depuis le niveau Compose vers le niveau View. Cela permet l'élément de participer au défilement imbriqué, mais il ne permet pas défilement automatique des éléments. À des composables qu'il n'est pas possible de faire défiler automatiquement, comme Box ou Column, les deltas de défilement sur ces composants se propagent dans le système de défilement imbriqué et les deltas n'atteignent pas NestedScrollConnection fourni par rememberNestedScrollInteropConnection(), Par conséquent, ces deltas n'atteindront pas le composant View parent. Pour résoudre ce problème, assurez-vous de définir également les modificateurs de défilement sur ces types de composables. Vous pouvez vous reporter à la section précédente Imbriquée faites défiler la page pour afficher des informations.

Un View parent non coopératif contenant un ComposeView enfant

Un View non coopérant est une vue qui n'implémente pas les interfaces NestedScrolling nécessaires côté View. Cela signifie que l'interopérabilité du défilement imbriqué avec ces Views ne fonctionne pas directement. RecyclerView et ViewPager2 sont des exemples de Views non coopérants.