Пагинация

Введение в пагинацию

Пагинация или постраничный вывод в приложении является одной из распространенных задач, и для упрощения ее реализации Compose предоставляет ряд компонентов-пагинаторов, в частности, компоненты VerticalPager и HorizontalPager. Эти компоненты позволяют перелистывать контент по горизонтали или по вертикали. Поведение по умолчанию — перелистывание страниц с помощью свайпа пальцем влево и вправо для HorizontalPager и вверх и вниз для VerticalPager. Пагинаторы также предоставляют интерфейс для перехода к определенным страницам и различные варианты управления и контроля поведением компонента пагинации. Стоит отметить, что эти компоненты используют ленивую загрузку (как LazyColumn/LazyRow), то есть по умолчанию непосредственно компонуются только те страницы, которые находятся в видимой области.

Компонент HorizontalPager применяется для создания горизонтальной пагинации. Он имеет следующие параметры:

@Composable
fun HorizontalPager(
    state: PagerState,
    modifier: Modifier = Modifier,
    contentPadding: PaddingValues = PaddingValues(0.dp),
    pageSize: PageSize = PageSize.Fill,
    beyondViewportPageCount: Int = PagerDefaults.BeyondViewportPageCount,
    pageSpacing: Dp = 0.dp,
    verticalAlignment: Alignment.Vertical = Alignment.CenterVertically,
    flingBehavior: TargetedFlingBehavior = PagerDefaults.flingBehavior(state = state),
    userScrollEnabled: Boolean = true,
    reverseLayout: Boolean = false,
    key: ((index: Int) -> Any)? = null,
    pageNestedScrollConnection: NestedScrollConnection = PagerDefaults.pageNestedScrollConnection(
        state,
        Orientation.Horizontal
    ),
    snapPosition: SnapPosition = SnapPosition.Start,
    pageContent: @Composable PagerScope.(page: Int) -> Unit
): Unit

• state: состояние пагинатора в виде объекта PagerState

• modifier: применяемые к компоненту функции модификатора

• contentPadding: отступ вокруг контента в виде объекта PaddingValues. Может применяться для добавления отступов перед первой страницей или после последней страницы.

• pageSize: определяет, как страницы будут выглядеть внутри компонента. Представляет значение типа PageSize.

• beyondViewportPageCount: количество страниц, которые располагаются до или после видимой части и которые надо предварительно скомпоновать. Служит для цели оптимизации для ускорения загрузки страниц.

• pageSpacing: отступы в пикселях между отдельными страницами в компоненте

• verticalAlignment: вертикальное выравнивание страниц внутри компонента.

• flingBehavior: определяет поведение для момента, когда выполнена прокрутка пальцем.

• userScrollEnabled: указывает, будет ли доступна прокрутка.

• reverseLayout: указывает, надо ли размещать содержимое (страницы) в обратном порядке.

• key: определяет уникальный ключ для каждого элемента с помощью функции типа (index: Int) -> Any. Ключ применяется для определения позиции при прокрутке. Если передается null, то позиция при прокрутке определяется с помощью позиции в списке.

• pageNestedScrollConnection: NestedScrollConnection = PagerDefaults.pageNestedScrollConnection(state,Orientation.Horizontal ) A NestedScrollConnection that dictates how this Pager behaves with nested lists. The default behavior will see Pager to consume all nested deltas.

• snapPosition: определяет, как компонент будет выполнять привязку страниц.

• pageContent: определяет содержимое страницы с помощью функции-компонента PagerScope.(page: Int) -> Unit.

VerticalPager располагает страницы по вертикали и имеет аналогичный набор параметров:

@Composable
fun VerticalPager(
    state: PagerState,
    modifier: Modifier = Modifier,
    contentPadding: PaddingValues = PaddingValues(0.dp),
    pageSize: PageSize = PageSize.Fill,
    beyondViewportPageCount: Int = PagerDefaults.BeyondViewportPageCount,
    pageSpacing: Dp = 0.dp,
    horizontalAlignment: Alignment.Horizontal = Alignment.CenterHorizontally,
    flingBehavior: TargetedFlingBehavior = PagerDefaults.flingBehavior(state = state),
    userScrollEnabled: Boolean = true,
    reverseLayout: Boolean = false,
    key: ((index: Int) -> Any)? = null,
    pageNestedScrollConnection: NestedScrollConnection = PagerDefaults.pageNestedScrollConnection(
        state,
        Orientation.Vertical
    ),
    snapPosition: SnapPosition = SnapPosition.Start,
    pageContent: @Composable PagerScope.(page: Int) -> Unit
): Unit

Единственное отличие, что для страниц здесь используется выравнивание по вертикали.

Состояние PagerState

Для определения HorizontalPager или VerticalPager прежде всего необходимо определить их состояние. Для управления состоянием пагинатора применяется объект PagerState. Класс PagerState определяет ряд свойств и методов, которые позволяют получить информацию о состоянии пагинатора, либо управлять его поведением, например, прокручивать контент. Наиболее распространенные свойства:

• pageCount: количество страниц

• currentPage: "текущая" страница (страница, наиболее близкая к текущей точке прокрутки)

Среди методов PagerState следует отметить следующие:

• scrollToPage(page): мгновенный переход к странице с номером page

• animateScrollToPage(page): плавный переход к странице с номером page

Для определения состояния применяется функция rememberPagerState()

@ExperimentalFoundationApi
@Composable
public fun rememberPagerState(
    initialPage: Int = 0,
    initialPageOffsetFraction: Float = 0f,
    pageCount: () -> Int
): PagerState

Эта функция принимает три параметра:

• initialPage: номер начальной страницы, которая будет отображаться первой.

• initialPageOffsetFraction: смещение начальной страницы в виде доли от размера страниц

• pageCount: количество страниц в пагинаторе.

Например, определим состояние для пагинатора, в котормом будет 10 страниц:

val pagerState = rememberPagerState { 10 }

Определение содержимого

Последний параметр компонентов-пагинаторов устанавливает содержимое, в качестве которого может выступать любой компонент. Для установки содержимого применяется функция (page: Int) -> Unit. Ее единственный параметр представляет индекс страницы (начиная с 0). Например, определим вертикальный пагинатор, где содержимое, то есть каждая страница представляет компонент Text, который отображает текущий номер страницы:

package com.example.helloapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.pager.VerticalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.sp

class MainActivity : ComponentActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent @OptIn(ExperimentalFoundationApi::class){
            val pagerState = rememberPagerState { 10 }
            VerticalPager(state = pagerState, Modifier.fillMaxWidth()) { page ->
                Text("Page $page", fontSize = 55.sp)
            }
        }
    }
}

В итоге создается 10 страниц, и с помощью свайпа пальцем вверх-вниз мы можем перемещаться по ним: