Карусель

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

Доступны четыре варианта расположения элементов в карусели, подходящие для различных сценариев использования:

• Мультипросмотр : включает товары разных размеров. Рекомендуется для просмотра большого количества товаров одновременно, например, фотографий.
• Uncontained : Содержит элементы одного размера, выходящие за пределы экрана. Может быть настроено для отображения большего количества текста или другого пользовательского интерфейса над или под каждым элементом.
• «Герой» : выделяет одно большое изображение, чтобы привлечь внимание, и дает представление о том, что будет дальше, с помощью небольшого элемента. Рекомендуется для выделения контента, который вы хотите подчеркнуть, например, миниатюр фильмов или сериалов.
• Полноэкранный режим : отображает один большой элемент от края до края экрана и прокручивается по вертикали. Рекомендуется для контента, высота которого превышает ширину.

На этой странице показано, как реализовать многооконные и неизолированные карусельные макеты. Дополнительную информацию о типах макетов см. в руководстве по Carousel Material 3 .

Поверхность API

Для реализации многостраничных и неконтейнерных каруселей используйте компонуемые объекты HorizontalMultiBrowseCarousel и HorizontalUncontainedCarousel . Эти компонуемые объекты имеют общие ключевые параметры:

• state : Экземпляр CarouselState , управляющий текущим индексом элемента и положением прокрутки. Создайте это состояние с помощью rememberCarouselState { itemCount } , где itemCount — общее количество элементов в карусели.
• itemSpacing : Определяет расстояние между соседними элементами в карусели.
• contentPadding : Применяет отступы вокруг области содержимого карусели. Используйте это для добавления пространства перед первым или после последнего элемента, а также для задания полей для элементов внутри прокручиваемой области.
• content : Компонуемая функция, принимающая целочисленный индекс. Используйте эту лямбда-функцию для определения пользовательского интерфейса для каждого элемента в карусели на основе его индекса.

Эти составные элементы различаются способом задания размеров:

• itemWidth (для HorizontalUncontainedCarousel ): Задает точную ширину каждого элемента в несвязанной карусели.
• preferredItemWidth (для HorizontalMultiBrowseCarousel ): Предлагает оптимальную ширину для элементов в многостраничной карусели, позволяя компоненту отображать несколько элементов, если позволяет пространство.

Пример: Карусель с несколькими страницами для просмотра

Этот фрагмент кода реализует карусель с возможностью просмотра нескольких страниц:

@Composable
fun CarouselExample_MultiBrowse() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val items = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Основные моменты, касающиеся кода.

• Определяет класс данных CarouselItem , который структурирует данные для каждого элемента в карусели.
• Создает и запоминает List объектов CarouselItem , заполненных графическими ресурсами и описаниями.
• Использует составной компонент HorizontalMultiBrowseCarousel , предназначенный для отображения нескольких элементов в карусели.
  • Состояние карусели инициализируется с помощью rememberCarouselState , которому передается общее количество элементов.
  • Для каждого элемента задан параметр preferredItemWidth (здесь 186.dp ), который определяет оптимальную ширину. Карусель использует этот параметр для определения количества элементов, которые могут поместиться на экране одновременно.
  • Параметр itemSpacing добавляет небольшой зазор между элементами.
  • Завершающая лямбда-функция класса HorizontalMultiBrowseCarousel перебирает элементы CarouselItems . На каждой итерации она извлекает элемент с индексом i и отображает Image , которое можно для него скомпоновать.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) применяет к каждому изображению предопределенную маску формы, закругляя углы.
  • contentDescription предоставляет описание доступности изображения.

Результат

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

Пример: Неограниченная карусель

Следующий фрагмент кода реализует карусель без контейнера:

@Composable
fun CarouselExample() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val carouselItems = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalUncontainedCarousel(
        state = rememberCarouselState { carouselItems.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        itemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = carouselItems[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Основные моменты, касающиеся кода.

• Компонент HorizontalUncontainedCarousel создает макет карусели.
  • Параметр itemWidth задает фиксированную ширину для каждого элемента в карусели.

Результат

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