Отложенные списки и сетки

Многим приложениям необходимо отображать коллекции элементов. В этом документе рассказывается, как эффективно сделать это в Jetpack Compose.

Если вы знаете, что в вашем случае прокрутка не требуется, вы можете использовать простой элемент Column или Row (в зависимости от направления) и выводить контент каждого элемента, перебирая список следующим образом:

@Composable
fun MessageList(messages: List<Message>) {
    Column {
        messages.forEach { message ->
            MessageRow(message)
        }
    }
}

Чтобы сделать Column прокручиваемым, используйте модификатор verticalScroll().

Ленивые списки

Если вам нужно показать большое количество элементов или список неизвестной длины, использование макета, такого как Column, может привести к проблемам производительности, поскольку все элементы будут скомпонованы и размещены независимо от того, видны они или нет.

Compose предоставляет набор компонентов, которые составляют и размещают только элементы, видимые в области просмотра компонента. К этим компонентам относятся LazyColumn и LazyRow.

Как следует из названия, разница между LazyColumn и LazyRow заключается в ориентации, в которой они размещают свои элементы и прокручивают их. LazyColumn – список с вертикальной прокруткой, а LazyRow – список с горизонтальной прокруткой.

Компоненты Lazy отличаются от большинства макетов в Compose. Вместо того чтобы принимать параметр блока контента @Composable, позволяющий приложениям напрямую генерировать composable-функции, Lazy-компоненты предоставляют блок LazyListScope.(). Блок LazyListScope предлагает DSL, который позволяет приложениям описывать содержимое элемента. Затем ленивый компонент отвечает за добавление содержимого каждого элемента в соответствии с требованиями макета и положения прокрутки.

LazyListScope DSL

DSL LazyListScope предоставляет ряд функций для описания элементов в макете. В самом простом случае item() добавляет один элемент, а items(Int) – несколько:

LazyColumn {
    // Add a single item
    item {
        Text(text = "First item")
    }

    // Add 5 items
    items(5) { index ->
        Text(text = "Item: $index")
    }

    // Add another single item
    item {
        Text(text = "Last item")
    }
}

Также есть ряд функций расширения, которые позволяют добавлять коллекции элементов, например List. Эти расширения позволяют легко перенести наш пример Column, приведенный выше:

/**
 * import androidx.compose.foundation.lazy.items
 */
LazyColumn {
    items(messages) { message ->
        MessageRow(message)
    }
}

Также существует вариант функции расширения items(), который называется itemsIndexed() и предоставляет индекс. Подробную информацию вы найдете в справочных материалах по LazyListScope.

Ленивые сетки

Для отображения элементов в виде сетки используются composable-функции LazyVerticalGrid и LazyHorizontalGrid. Ленивая вертикальная сетка будет отображать свои элементы в вертикально прокручиваемом контейнере, охватывающем несколько столбцов, в то время как ленивые горизонтальные сетки будут иметь такое же поведение по горизонтальной оси.

Сетки имеют те же мощные возможности API, что и списки, а также используют очень похожий DSL – LazyGridScope.() для описания контента.

Скриншот телефона с сеткой фотографий

Параметр columns в LazyVerticalGrid и параметр rows в LazyHorizontalGrid определяют, как ячейки формируются в столбцы или строки. В следующем примере элементы отображаются в виде сетки, а с помощью GridCells.Adaptive задается минимальная ширина каждого столбца – 128.dp:

LazyVerticalGrid(
    columns = GridCells.Adaptive(minSize = 128.dp)
) {
    items(photos) { photo ->
        PhotoItem(photo)
    }
}

LazyVerticalGrid позволяет указать ширину элементов, а затем сетка будет соответствовать как можно большему количеству столбцов. Оставшаяся ширина распределяется поровну между столбцами после того, как будет рассчитано их количество. Такой адаптивный способ определения размеров особенно полезен для отображения наборов элементов на экранах разных размеров.

Если вы знаете точное количество столбцов, которые нужно использовать, вы можете указать экземпляр GridCells.Fixed, содержащий количество необходимых столбцов.

Если в вашем дизайне только некоторые элементы должны иметь нестандартные размеры, вы можете использовать поддержку сетки для предоставления настраиваемых диапазонов столбцов для элементов. Укажите диапазон столбцов с помощью параметра span методов LazyGridScope DSL, item и items. maxLineSpan – одно из значений области охвата, которое особенно полезно при использовании адаптивного размера, поскольку количество столбцов не фиксировано. В этом примере показано, как задать полный диапазон строк:

LazyVerticalGrid(
    columns = GridCells.Adaptive(minSize = 30.dp)
) {
    item(span = {
        // LazyGridItemSpanScope:
        // maxLineSpan
        GridItemSpan(maxLineSpan)
    }) {
        CategoryCard("Fruits")
    }
    // ...
}

Ленивая ступенчатая сетка

LazyVerticalStaggeredGrid и LazyHorizontalStaggeredGrid – это composable-функции, которые позволяют создавать сетку элементов с ленивой загрузкой и чередованием. Ленивая вертикальная ступенчатая сетка отображает свои элементы в контейнере с вертикальной прокруткой, который охватывает несколько столбцов и позволяет отдельным элементам иметь разную высоту. Ленивые горизонтальные сетки ведут себя так же по горизонтальной оси с элементами разной ширины.

Ниже приведен пример использования LazyVerticalStaggeredGrid с шириной 200.dp для каждого элемента:

LazyVerticalStaggeredGrid(
    columns = StaggeredGridCells.Adaptive(200.dp),
    verticalItemSpacing = 4.dp,
    horizontalArrangement = Arrangement.spacedBy(4.dp),
    content = {
        items(randomSizedPhotos) { photo ->
            AsyncImage(
                model = photo,
                contentScale = ContentScale.Crop,
                contentDescription = null,
                modifier = Modifier
                    .fillMaxWidth()
                    .wrapContentHeight()
            )
        }
    },
    modifier = Modifier.fillMaxSize()
)

Рисунок 1. Пример вертикальной сетки с ленивой загрузкой и элементами разной высоты

Чтобы задать фиксированное количество столбцов, используйте StaggeredGridCells.Fixed(columns) вместо StaggeredGridCells.Adaptive. В этом случае доступная ширина делится на количество столбцов (или строк для горизонтальной сетки), и каждый элемент занимает эту ширину (или высоту для горизонтальной сетки):

LazyVerticalStaggeredGrid(
    columns = StaggeredGridCells.Fixed(3),
    verticalItemSpacing = 4.dp,
    horizontalArrangement = Arrangement.spacedBy(4.dp),
    content = {
        items(randomSizedPhotos) { photo ->
            AsyncImage(
                model = photo,
                contentScale = ContentScale.Crop,
                contentDescription = null,
                modifier = Modifier
                    .fillMaxWidth()
                    .wrapContentHeight()
            )
        }
    },
    modifier = Modifier.fillMaxSize()
)
Ленивая ступенчатая сетка изображений в Compose
Рисунок 2. Пример вертикальной сетки с фиксированными столбцами и элементами разной высоты

Повысьте производительность прокрутки с помощью LazyLayoutCacheWindow

LazyLayoutCacheWindow – это API, предназначенный для повышения производительности прокрутки в списках, сетках и ступенчатых сетках. В CacheWindow вы можете определить виртуальное пространство, в котором элементы могут быть предварительно загружены (перед окном) или сохранены (за окном) во время событий прокрутки. Это означает, что композиция и измерение элементов заполняют внутренний кеш. Когда эти элементы действительно понадобятся (когда они станут видимыми), их отображение займет значительно меньше времени, чем если бы они были созданы с нуля.

Для всех коллекций с отложенной загрузкой по умолчанию используется стратегия предварительной выборки CacheWindow. По умолчанию расстояние упреждающей выборки составляет от 10 % до 50 % области просмотра. При этом размер окна за пределами экрана устанавливается равным 0 пикселей, а кеширование без прокрутки отключается.

Настройка окна

Вы можете настроить окно кеша, используя доли области просмотра или фиксированные расстояния в Dp:

// Fraction-based cache window: prefetch 50% of viewport ahead, keep 20% behind
LazyColumn(
    cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f)
) {
    items(itemsList) { item -> Text("Item $item") }
}

// Dp-based cache window: prefetch 150.dp ahead, keep 50.dp behind
LazyVerticalGrid(
    columns = GridCells.Fixed(3),
    cacheWindow = LazyLayoutCacheWindow(
        ahead = 150.dp,
        behind = 50.dp,
        isNonScrollCachingEnabled = true
    )
) {
    items(itemsList) { item -> Text("Item $item") }
}

Окно кеша управляет двумя отдельными областями относительно направления прокрутки:

  • Окно упреждения. Фреймворк предварительно компонует и измеряет предстоящие элементы до того, как они попадут в видимую область просмотра. По умолчанию используется значение 0dp или 0f.
  • За окном. Фреймворк сохраняет недавно прокрученные элементы, не удаляя их. Когда пользователи меняют направление прокрутки, сохраненные элементы отображаются сразу, без повторной компоновки или повторного измерения. По умолчанию используется значение 0dp или 0f.

Кроме того, если задано значение isNonScrollCachingEnabled = true (по умолчанию), макет заполняет окно упреждения в периоды бездействия, когда пользователь не прокручивает экран. К ним относятся начальный проход макета, обновление набора данных и изменение порядка элементов. Если задано значение false, кеширование происходит только во время прокрутки.

Свой цвет CacheWindow

Если фиксированные расстояния или доли области просмотра не соответствуют шаблонам макета, вы можете реализовать интерфейс LazyLayoutCacheWindow напрямую:

interface LazyLayoutCacheWindow {
    fun Density.calculateAheadWindow(viewport: Int): Int = 0
    fun Density.calculateBehindWindow(viewport: Int): Int = 0
    val isNonScrollCachingEnabled: Boolean get() = false
}

Реализуйте методы вычисления, чтобы возвращать предпочтительный размер окна в пикселях для заданного размера области просмотра:

class ScaledCacheWindow(
    val someLayoutState: LayoutState
) : LazyLayoutCacheWindow {
    override fun Density.calculateAheadWindow(viewport: Int): Int {
        return someLayoutState.specialDynamicCalculation().coerceAtMost(viewport * 5)
    }

    override fun equals(other: Any?): Boolean {
        if (this === other) return true
        if (other !is ScaledCacheWindow) return false
        return someLayoutState == other.someLayoutState
    }

    override fun hashCode(): Int {
        return someLayoutState.hashCode()
    }
}

@Composable
fun ScaledCacheWindowSample() {
    val state = rememberLazyListState()
    val newCacheWindow = remember { ScaledCacheWindow(state) }
    LazyColumn(
        state = state,
        cacheWindow = newCacheWindow,
    ) {
        items(100) { index ->
            Text(
                text = "Item #$index",
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(16.dp),
            )
        }
    }
}

Руководство по переходу

Первоначальные API конфигурации предварительной выборки (PrefetchStrategy) и первая версия LazyLayoutCacheWindow позволяли выполнять конфигурацию в состояниях, но теперь эта функция устарела. В этом разделе рассказывается, как перейти с устаревших API и параметров, перечисленных ниже.

  • Параметры cacheWindow, зависящие от штата, в rememberLazyListState и rememberLazyGridState.
  • LazyListPrefetchStrategy и LazyGridPrefetchStrategy с LazyLayoutCacheWindow.

Вариант 1. Переместить аргументы (cacheWindow)

Чтобы перейти на рекомендуемые API, перенесите аргументы cacheWindow из rememberLazyListState и rememberLazyGridState в аргумент cacheWindow в LazyColumn, LazyRow, LazyVerticalGrid и LazyHorizontalGrid. LazyVerticalStaggeredGrid и LazyHorizontalStaggeredGrid уже реализуют новую парадигму в composable-функции макета.

// Before (Experimental in Compose 1.9 to 1.12, now Deprecated)
val state = rememberLazyListState(
    cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f)
)
LazyColumn(state = state) {
    items(itemsList) { item -> Text("Item $item") }
}

// Now in Compose 1.13 (Stable)
val state = rememberLazyListState()
LazyColumn(
    state = state,
    cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f)
) {
    items(itemsList) { item -> Text("Item $item") }
}

Вариант 2. Замените LazyListPrefetchStrategy и LazyGridPrefetchStrategy

Замените устаревшие API LazyListPrefetchStrategy и LazyGridPrefetchStrategy на LazyLayoutCacheWindow. Теперь все действия по предварительной загрузке выполняются с помощью cacheWindow. Это изменение влияет на поведение предварительной выборки в следующих сценариях:

  • Небольшие элементы. Если элементы занимают менее 10 % области просмотра, Compose предварительно выбирает несколько элементов. Это уменьшает задержку прокрутки при быстром пролистывании.
  • Крупные элементы. Если отдельные элементы занимают более 50 % области просмотра, закрепленное окно не может охватить весь следующий элемент. Если у вас есть высокие элементы, например ленты медиаконтента или цепочки сообщений, вы можете заметить поздние триггеры предзагрузки. В этом случае следует настроить окно упреждения.
  • Если в вашей стратегии использовалось планирование для отдельных объектов, перенесите логику в LazyLayoutCacheWindow.calculateAheadWindow. Чтобы воспроизвести аналогичное поведение предварительной выборки, состоящее в составлении и измерении одного элемента впереди в направлении прокрутки, реализуйте настраиваемое окно на основе видимых показателей элементов. Обратите внимание, что хотя это не совсем то же самое, это наиболее близкий вариант, который можно получить при использовании упреждающей выборки на основе окна:

val state = rememberLazyListState()
val legacyCacheWindow = remember(state) {
    object : LazyLayoutCacheWindow {
        override fun Density.calculateAheadWindow(viewport: Int): Int {
            val visibleItems = state.layoutInfo.visibleItemsInfo
            if (visibleItems.isEmpty()) return 0
            val averageItemHeight = visibleItems.sumOf { it.size } / visibleItems.size
            return averageItemHeight
        }
    }
}
LazyColumn(
    state = state,
    cacheWindow = legacyCacheWindow
) {
    items(itemsList) { item -> Text("Item $item") }
}

Поля контента

Иногда вам нужно будет добавить отступы по краям контента. Для этого в параметр contentPadding ленивых компонентов можно передать PaddingValues:

LazyColumn(
    contentPadding = PaddingValues(horizontal = 16.dp, vertical = 8.dp),
) {
    // ...
}

В этом примере мы добавляем отступы 16.dp по горизонтали (слева и справа) и 8.dp сверху и снизу.

Обратите внимание, что это поле применяется к контенту, а не к самому элементу LazyColumn. В примере выше у первого элемента будет отступ сверху 8.dp, у последнего – отступ снизу 8.dp, а у всех элементов – отступы слева и справа 16.dp.

Другой пример: вы можете передать PaddingValues из Scaffold в contentPadding из LazyColumn. Ознакомьтесь с руководством по полноэкранному режиму.

Интервалы между элементами контента

Чтобы добавить интервал между элементами, используйте Arrangement.spacedBy(). В примере ниже между элементами добавляется пространство размером 4.dp:

LazyColumn(
    verticalArrangement = Arrangement.spacedBy(4.dp),
) {
    // ...
}

Аналогично для LazyRow:

LazyRow(
    horizontalArrangement = Arrangement.spacedBy(4.dp),
) {
    // ...
}

Однако сетки могут быть как вертикальными, так и горизонтальными:

LazyVerticalGrid(
    columns = GridCells.Fixed(2),
    verticalArrangement = Arrangement.spacedBy(16.dp),
    horizontalArrangement = Arrangement.spacedBy(16.dp)
) {
    items(photos) { item ->
        PhotoItem(item)
    }
}

Ключи элементов

По умолчанию состояние каждого элемента привязано к его позиции в списке или сетке. Однако это может вызвать проблемы, если набор данных изменится, поскольку элементы, которые меняют положение, фактически теряют любое запомненное состояние. Если вы представите сценарий LazyRow в LazyColumn, если строка изменит положение элемента, пользователь потеряет свою позицию прокрутки в строке.

Чтобы этого избежать, вы можете указать стабильный и уникальный ключ для каждого элемента, передав блок в параметр key. Предоставление стабильного ключа позволяет согласовывать состояние элемента при изменении набора данных:

LazyColumn {
    items(
        items = messages,
        key = { message ->
            // Return a stable + unique key for the item
            message.id
        }
    ) { message ->
        MessageRow(message)
    }
}

Предоставляя ключи, вы помогаете Compose правильно обрабатывать изменения порядка. Например, если ваш элемент содержит запомненное состояние, установка ключей позволит Compose перемещать это состояние вместе с элементом при изменении его положения.

LazyColumn {
    items(books, key = { it.id }) {
        val rememberedValue = remember {
            Random.nextInt()
        }
    }
}

Однако есть одно ограничение на типы, которые можно использовать в качестве ключей элементов. Тип ключа должен поддерживаться Bundle – механизмом Android для сохранения состояний при повторном создании действия. Bundle поддерживает такие типы, как примитивы, перечисления или Parcelable.

LazyColumn {
    items(books, key = {
        // primitives, enums, Parcelable, etc.
    }) {
        // ...
    }
}

Ключ должен поддерживаться Bundle, чтобы rememberSaveable внутри composable-функции элемента можно было восстановить при повторном создании действия или даже когда вы прокручиваете страницу за пределы этого элемента и обратно.

LazyColumn {
    items(books, key = { it.id }) {
        val rememberedValue = rememberSaveable {
            Random.nextInt()
        }
    }
}

Анимация объектов

Если вы использовали виджет RecyclerView, то знаете, что он автоматически анимирует изменения элементов. Ленивые макеты предоставляют ту же функциональность для изменения порядка элементов. API прост – вам нужно лишь задать модификатор animateItem для контента элемента:

LazyColumn {
    // It is important to provide a key to each item to ensure animateItem() works as expected.
    items(books, key = { it.id }) {
        Row(Modifier.animateItem()) {
            // ...
        }
    }
}

При необходимости вы можете задать собственные настройки анимации:

LazyColumn {
    items(books, key = { it.id }) {
        Row(
            Modifier.animateItem(
                fadeInSpec = tween(durationMillis = 250),
                fadeOutSpec = tween(durationMillis = 100),
                placementSpec = spring(stiffness = Spring.StiffnessLow, dampingRatio = Spring.DampingRatioMediumBouncy)
            )
        ) {
            // ...
        }
    }
}

Убедитесь, что вы указали ключи для элементов, чтобы можно было найти новую позицию для перемещенного элемента.

Пример: анимация элементов в ленивых списках

С помощью Compose вы можете анимировать изменения элементов в ленивых списках. При совместном использовании следующие фрагменты реализуют анимацию при добавлении, удалении и изменении порядка элементов ленивого списка.

Этот фрагмент отображает список строк с анимированными переходами, когда элементы добавляются, удаляются или переупорядочиваются:

@Composable
fun ListAnimatedItems(
    items: List<String>,
    modifier: Modifier = Modifier
) {
    LazyColumn(modifier) {
        // Use a unique key per item, so that animations work as expected.
        items(items, key = { it }) {
            ListItem(
                headlineContent = { Text(it) },
                modifier = Modifier
                    .animateItem(
                        // Optionally add custom animation specs
                    )
                    .fillParentMaxWidth()
                    .padding(horizontal = 8.dp, vertical = 0.dp),
            )
        }
    }
}

Важные сведения о коде

  • ListAnimatedItems показывает список строк в LazyColumn с анимированными переходами при изменении элементов.
  • Функция items назначает уникальный ключ каждому элементу в списке. Compose использует ключи, чтобы отслеживать элементы и определять изменения в их позициях.
  • ListItem определяет макет каждого элемента списка. Он принимает параметр headlineContent, который определяет основной контент элемента.
  • Модификатор animateItem применяет анимацию по умолчанию к добавлению, удалению и перемещению элементов.

В следующем фрагменте кода показан экран с элементами управления для добавления и удаления элементов, а также сортировки предопределенного списка:

@Composable
private fun ListAnimatedItemsExample(
    data: List<String>,
    modifier: Modifier = Modifier,
    onAddItem: () -> Unit = {},
    onRemoveItem: () -> Unit = {},
    resetOrder: () -> Unit = {},
    onSortAlphabetically: () -> Unit = {},
    onSortByLength: () -> Unit = {},
) {
    val canAddItem = data.size < 10
    val canRemoveItem = data.isNotEmpty()

    Scaffold(modifier) { paddingValues ->
        Column(
            modifier = Modifier
                .padding(paddingValues)
                .fillMaxSize()
        ) {
            // Buttons that change the value of displayedItems.
            AddRemoveButtons(canAddItem, canRemoveItem, onAddItem, onRemoveItem)
            OrderButtons(resetOrder, onSortAlphabetically, onSortByLength)

            // List that displays the values of displayedItems.
            ListAnimatedItems(data)
        }
    }
}

Важные сведения о коде

  • ListAnimatedItemsExample представляет экран, который включает элементы управления для добавления, удаления и сортировки элементов.
    • onAddItem и onRemoveItem – это лямбда-выражения, которые передаются в AddRemoveButtons, чтобы добавлять и удалять элементы из списка.
    • resetOrder, onSortAlphabetically и onSortByLength – это лямбда-выражения, которые передаются в OrderButtons, чтобы изменить порядок элементов в списке.
  • AddRemoveButtons показывает кнопки "Добавить" и "Удалить". Он включает и отключает кнопки, а также обрабатывает нажатия на них.
  • OrderButtons показывает кнопки для изменения порядка в списке. Она получает лямбда-функции для сброса порядка и сортировки списка по длине или в алфавитном порядке.
  • ListAnimatedItems вызывает composable-функцию ListAnimatedItems, передавая список data, чтобы показать анимированный список строк. data is defined elsewhere.

Этот фрагмент создает интерфейс с кнопками Добавить элемент и Удалить элемент:

@Composable
private fun AddRemoveButtons(
    canAddItem: Boolean,
    canRemoveItem: Boolean,
    onAddItem: () -> Unit,
    onRemoveItem: () -> Unit
) {
    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.Center
    ) {
        Button(enabled = canAddItem, onClick = onAddItem) {
            Text("Add Item")
        }
        Spacer(modifier = Modifier.padding(25.dp))
        Button(enabled = canRemoveItem, onClick = onRemoveItem) {
            Text("Delete Item")
        }
    }
}

Важные сведения о коде

  • AddRemoveButtons показывает ряд кнопок для добавления и удаления элементов списка.
  • Параметры canAddItem и canRemoveItem управляют состоянием кнопок. Если для canAddItem или canRemoveItem задано значение False, соответствующая кнопка отключена.
  • Параметры onAddItem и onRemoveItem – это лямбда-выражения, которые выполняются, когда пользователь нажимает соответствующую кнопку.

Наконец, этот фрагмент кода отображает три кнопки для сортировки списка (Сбросить, Алфавитный и Длина):

@Composable
private fun OrderButtons(
    resetOrder: () -> Unit,
    orderAlphabetically: () -> Unit,
    orderByLength: () -> Unit
) {
    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.Center
    ) {
        var selectedIndex by remember { mutableIntStateOf(0) }
        val options = listOf("Reset", "Alphabetical", "Length")

        SingleChoiceSegmentedButtonRow {
            options.forEachIndexed { index, label ->
                SegmentedButton(
                    shape = SegmentedButtonDefaults.itemShape(
                        index = index,
                        count = options.size
                    ),
                    onClick = {
                        Log.d("AnimatedOrderedList", "selectedIndex: $selectedIndex")
                        selectedIndex = index
                        when (options[selectedIndex]) {
                            "Reset" -> resetOrder()
                            "Alphabetical" -> orderAlphabetically()
                            "Length" -> orderByLength()
                        }
                    },
                    selected = index == selectedIndex
                ) {
                    Text(label)
                }
            }
        }
    }
}

Важные сведения о коде

  • OrderButtons показывает SingleChoiceSegmentedButtonRow, чтобы пользователи могли выбрать метод сортировки списка или сбросить порядок списка. Компонент SegmentedButton позволяет выбрать один вариант из списка.
  • resetOrder, orderAlphabetically и orderByLength – это лямбда-функции, которые выполняются при нажатии соответствующей кнопки.
  • Переменная состояния selectedIndex отслеживает выбранный вариант.

Результат

В этом видео показан результат выполнения предыдущих фрагментов кода при изменении порядка элементов:

Рисунок 1. Список, который анимирует переходы элементов при их добавлении, удалении или сортировке.

Закрепленные заголовки

Шаблон "закрепленный заголовок" полезен при отображении списков сгруппированных данных. Ниже вы можете увидеть пример списка контактов, сгруппированных по первой букве имени:

Видео, на котором показано, как прокручивать список контактов на телефоне вверх и вниз

Чтобы закрепить заголовок с помощью LazyColumn, можно использовать stickyHeader().

функцию, которая предоставляет контент заголовка:

@Composable
fun ListWithHeader(items: List<Item>) {
    LazyColumn {
        stickyHeader {
            Header()
        }

        items(items) { item ->
            ItemRow(item)
        }
    }
}

Чтобы создать список с несколькими заголовками, как в примере со списком контактов выше, можно сделать следующее:

// This ideally would be done in the ViewModel
val grouped = contacts.groupBy { it.firstName[0] }

@Composable
fun ContactsList(grouped: Map<Char, List<Contact>>) {
    LazyColumn {
        grouped.forEach { (initial, contactsForInitial) ->
            stickyHeader {
                CharacterHeader(initial)
            }

            items(contactsForInitial) { contact ->
                ContactListItem(contact)
            }
        }
    }
}

Реакция на позицию прокрутки

Многим приложениям необходимо реагировать и прислушиваться к изменениям положения прокрутки и макета элементов. Компоненты Lazy поддерживают этот вариант использования, поднимая LazyListState:

@Composable
fun MessageList(messages: List<Message>) {
    // Remember our own LazyListState
    val listState = rememberLazyListState()

    // Provide it to LazyColumn
    LazyColumn(state = listState) {
        // ...
    }
}

В простых случаях приложениям обычно требуется информация только о первом видимом элементе. Для этого в типе LazyListState предусмотрены свойства firstVisibleItemIndex и firstVisibleItemScrollOffset.

Если мы используем пример показа и скрытия кнопки в зависимости от того, прокрутил ли пользователь первый элемент:

@Composable
fun MessageList(messages: List<Message>) {
    Box {
        val listState = rememberLazyListState()

        LazyColumn(state = listState) {
            // ...
        }

        // Show the button if the first visible item is past
        // the first item. We use a remembered derived state to
        // minimize unnecessary compositions
        val showButton by remember {
            derivedStateOf {
                listState.firstVisibleItemIndex > 0
            }
        }

        AnimatedVisibility(visible = showButton) {
            ScrollToTopButton()
        }
    }
}

Чтение состояния непосредственно в композиции полезно, когда вам нужно обновить другие составные элементы пользовательского интерфейса, но есть также сценарии, в которых событие не нужно обрабатывать в той же композиции. Распространенный пример – отправка события аналитики, когда пользователь прокручивает страницу до определенной точки. Чтобы эффективно справиться с этим, мы можем использовать snapshotFlow():

val listState = rememberLazyListState()

LazyColumn(state = listState) {
    // ...
}

LaunchedEffect(listState) {
    snapshotFlow { listState.firstVisibleItemIndex }
        .map { index -> index > 0 }
        .distinctUntilChanged()
        .filter { it }
        .collect {
            MyAnalyticsService.sendScrolledPastFirstItemEvent()
        }
}

LazyListState также предоставляет информацию обо всех отображаемых в данный момент элементах и их границах на экране через свойство layoutInfo. Дополнительную информацию можно найти в описании класса LazyListLayoutInfo.

Управление позицией прокрутки

Помимо реагирования на положение прокрутки, приложениям также полезно иметь возможность контролировать положение прокрутки. LazyListState поддерживает это с помощью функции scrollToItem(), которая мгновенно перемещает позицию прокрутки, и animateScrollToItem(), которая прокручивает с помощью анимации (также известной как плавная прокрутка):

@Composable
fun MessageList(messages: List<Message>) {
    val listState = rememberLazyListState()
    // Remember a CoroutineScope to be able to launch
    val coroutineScope = rememberCoroutineScope()

    LazyColumn(state = listState) {
        // ...
    }

    ScrollToTopButton(
        onClick = {
            coroutineScope.launch {
                // Animate scroll to the first item
                listState.animateScrollToItem(index = 0)
            }
        }
    )
}

Большие наборы данных (разбиение на страницы)

Библиотека Paging позволяет приложениям поддерживать большие списки элементов, загружая и отображая небольшие фрагменты списка по мере необходимости. Paging 3.0 и более поздние версии поддерживают Compose через библиотеку androidx.paging:paging-compose.

Чтобы показать список контента, разбитого на страницы, можно использовать функцию расширения collectAsLazyPagingItems(), а затем передать возвращенный объект LazyPagingItems в items() в LazyColumn. Как и в случае с поддержкой разбиения на страницы в представлениях, вы можете отображать плейсхолдеры во время загрузки данных, проверяя, является ли item null:

@Composable
fun MessageList(pager: Pager<Int, Message>) {
    val lazyPagingItems = pager.flow.collectAsLazyPagingItems()

    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it.id }
        ) { index ->
            val message = lazyPagingItems[index]
            if (message != null) {
                MessageRow(message)
            } else {
                MessagePlaceholder()
            }
        }
    }
}

Советы по использованию ленивых макетов

Чтобы ленивые макеты работали правильно, следуйте приведенным ниже советам.

Не используйте объекты размером 0 пикселей

Это может произойти, например, если вы ожидаете асинхронного получения некоторых данных, таких как изображения, для заполнения элементов списка на более позднем этапе. Это приведет к тому, что ленивый макет скомпонует все свои элементы при первом измерении, поскольку их высота равна 0 пикселей и все они могут поместиться в области просмотра. После загрузки элементов и увеличения их высоты ленивые макеты отбрасывают все остальные элементы, которые были напрасно скомпонованы в первый раз, поскольку они не могут поместиться в области просмотра. Чтобы избежать этого, вам следует установить размеры по умолчанию для ваших элементов, чтобы ленивый макет мог правильно рассчитать, сколько элементов на самом деле может поместиться в области просмотра:

@Composable
fun Item(imageUrl: String) {
    AsyncImage(
        model = rememberAsyncImagePainter(model = imageUrl),
        modifier = Modifier.size(30.dp),
        contentDescription = null
        // ...
    )
}

Если вы знаете примерный размер элементов после асинхронной загрузки данных, рекомендуем сделать так, чтобы размер элементов до и после загрузки оставался одинаковым, например добавив несколько плейсхолдеров. Это поможет сохранить правильную позицию прокрутки.

Не вкладывайте друг в друга компоненты, которые прокручиваются в одном направлении.

Это относится только к случаям, когда вложенные прокручиваемые дочерние элементы без предопределенного размера находятся внутри другого прокручиваемого родительского элемента в том же направлении. Например, если вы попытаетесь вложить дочерний элемент LazyColumn без фиксированной высоты в родительский элемент Column с вертикальной прокруткой:

// throws IllegalStateException
Column(
    modifier = Modifier.verticalScroll(state)
) {
    LazyColumn {
        // ...
    }
}

Вместо этого можно поместить все composable-функции в один родительский элемент LazyColumn и использовать его DSL для передачи разных типов контента. Это позволяет выводить как отдельные элементы, так и несколько элементов списка в одном месте:

LazyColumn {
    item {
        Header()
    }
    items(data) { item ->
        PhotoItem(item)
    }
    item {
        Footer()
    }
}

Обратите внимание, что вложенные макеты с разным направлением прокрутки, например родительский Row и дочерний LazyColumn, разрешены.

Row(
    modifier = Modifier.horizontalScroll(scrollState)
) {
    LazyColumn {
        // ...
    }
}

А также случаи, когда вы по-прежнему используете макеты с одинаковым направлением, но также устанавливаете фиксированный размер для вложенных дочерних элементов:

Column(
    modifier = Modifier.verticalScroll(scrollState)
) {
    LazyColumn(
        modifier = Modifier.height(200.dp)
    ) {
        // ...
    }
}

Не добавляйте несколько элементов в один объект

В этом примере лямбда-выражение второго элемента выдает два элемента в одном блоке:

LazyVerticalGrid(
    columns = GridCells.Adaptive(100.dp)
) {
    item { Item(0) }
    item {
        Item(1)
        Item(2)
    }
    item { Item(3) }
    // ...
}

Ленивые макеты будут обрабатывать это так, как ожидается: они будут размещать элементы один за другим, как если бы они были разными элементами. Однако при этом возникает пара проблем.

Когда несколько элементов создаются как часть одного элемента, они обрабатываются как один объект, то есть их больше нельзя компоновать по отдельности. Если один элемент становится видимым на экране, то все элементы, соответствующие элементу, должны быть составлены и измерены. Если использовать их слишком часто, это может снизить эффективность. В крайнем случае, когда все элементы помещаются в один элемент, это полностью сводит на нет цель использования ленивых макетов. Помимо возможных проблем с производительностью, размещение нескольких элементов в одном объекте также будет мешать работе scrollToItem() и animateScrollToItem().

Однако в некоторых случаях в один элемент можно поместить несколько, например если в списке есть разделители. Вы не хотите, чтобы разделители меняли индексы прокрутки, поскольку они не должны считаться независимыми элементами. Кроме того, разделители не влияют на производительность, поскольку они небольшие. Разделитель должен быть виден, когда виден элемент перед ним, поэтому он может быть частью предыдущего элемента:

LazyVerticalGrid(
    columns = GridCells.Adaptive(100.dp)
) {
    item { Item(0) }
    item {
        Item(1)
        Divider()
    }
    item { Item(2) }
    // ...
}

Используйте собственные аранжировки

Обычно ленивые списки содержат много элементов и занимают больше размера контейнера прокрутки. Однако, когда ваш список заполнен несколькими элементами, ваш дизайн может иметь более конкретные требования к тому, как они должны быть расположены в области просмотра.

Для этого можно использовать специальную вертикаль Arrangement и передать ее в LazyColumn. В примере ниже объекту TopWithFooter нужно реализовать только метод arrange. Во-первых, он будет размещать элементы один за другим. Во-вторых, если общая высота контента меньше высоты области просмотра, нижний колонтитул будет расположен внизу:

object TopWithFooter : Arrangement.Vertical {
    override fun Density.arrange(
        totalSize: Int,
        sizes: IntArray,
        outPositions: IntArray
    ) {
        var y = 0
        sizes.forEachIndexed { index, size ->
            outPositions[index] = y
            y += size
        }
        if (y < totalSize) {
            val lastIndex = outPositions.lastIndex
            outPositions[lastIndex] = totalSize - sizes.last()
        }
    }
}

Рекомендуем добавить contentType

Начиная с версии Compose 1.2, чтобы повысить производительность ленивого макета, рекомендуется добавить в списки или сетки contentType. Это позволяет указать тип контента для каждого элемента макета, если вы составляете список или сетку, состоящую из нескольких элементов разных типов:

LazyColumn {
    items(elements, contentType = { it.type }) {
        // ...
    }
}

Если вы укажете contentType, Compose сможет повторно использовать композиции только между элементами одного типа. Повторное использование более эффективно, когда вы создаете элементы похожей структуры. Указание типов контента гарантирует, что Compose не попытается создать элемент типа A поверх совершенно другого элемента типа B. Это помогает максимально эффективно использовать повторное использование композиции и производительность вашего ленивого макета.

Оценка эффективности

Надежно измерить производительность ленивого макета можно только в режиме выпуска и с включенной оптимизацией R8. В отладочных сборках прокрутка ленивых макетов может быть медленнее. Подробнее о производительности Compose…

Дополнительные ресурсы