Carousel

用于展示可滚动项目集合的 Jetpack Compose Carousel 组件。

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.1

Expo UI 提供三个与官方 Jetpack Compose Carousel API 对应的轮播组件：HorizontalCenteredHeroCarousel、HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel。

注意： Carousel 是一个水平滚动组件，因此父级 Host 必须在滚动轴上提供有限宽度。请将 matchContents={{ vertical: true }} 与 style={{ width: '100%' }}（或任意有限宽度）一起使用。详情请参阅 Host 参考中的匹配内容。

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

HorizontalCenteredHeroCarousel

在两个较小的预览项之间居中显示一个较大的主展示项，适合突出展示电影海报等内容。

CenteredHeroExample.tsx

import {
  Host,
  HorizontalCenteredHeroCarousel,
  Box,
  Text,
} from '@expo/ui/jetpack-compose';
import {
  size,
  background,
  maskClip,
  Shapes,
} from '@expo/ui/jetpack-compose/modifiers';

export default function CenteredHeroExample() {
  const colors = [
    '#6200EE',
    '#03DAC5',
    '#FF5722',
    '#4CAF50',
    '#2196F3',
  ];

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <HorizontalCenteredHeroCarousel itemSpacing={8}>
        {colors.map((color, index) => (
          <Box
            key={index}
            contentAlignment="center"
            modifiers={[
              size(300, 200),
              maskClip(Shapes.RoundedCorner(28)),
              background(color),
            ]}>
            <Text color="#FFFFFF">Slide {index + 1}</Text>
          </Box>
        ))}
      </HorizontalCenteredHeroCarousel>
    </Host>
  );
}

HorizontalMultiBrowseCarousel

在较大的项目旁显示较小的预览项，让用户浏览后续内容。

MultiBrowseExample.tsx

import {
  Host,
  HorizontalMultiBrowseCarousel,
  Box,
  Text,
} from '@expo/ui/jetpack-compose';
import {
  size,
  background,
} from '@expo/ui/jetpack-compose/modifiers';

export default function MultiBrowseExample() {
  const colors = [
    '#6200EE',
    '#03DAC5',
    '#FF5722',
    '#4CAF50',
    '#2196F3',
  ];

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <HorizontalMultiBrowseCarousel
        preferredItemWidth={200}
        itemSpacing={8}
        flingBehavior="singleAdvance">
        {colors.map((color, index) => (
          <Box
            key={index}
            contentAlignment="center"
            modifiers={[size(200, 180), background(color)]}>
            <Text color="#FFFFFF">Card {index + 1}</Text>
          </Box>
        ))}
      </HorizontalMultiBrowseCarousel>
    </Host>
  );
}

HorizontalUncontainedCarousel

每个项目都有固定宽度，并支持自由滚动。

UncontainedExample.tsx

import {
  Host,
  HorizontalUncontainedCarousel,
  Box,
  Text,
} from '@expo/ui/jetpack-compose';
import {
  size,
  background,
} from '@expo/ui/jetpack-compose/modifiers';

export default function UncontainedExample() {
  const items = [
    'Photo 1',
    'Photo 2',
    'Photo 3',
    'Photo 4',
    'Photo 5',
  ];

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <HorizontalUncontainedCarousel
        itemWidth={160}
        itemSpacing={12}
        contentPadding={{ start: 16, top: 0, end: 16, bottom: 0 }}>
        {items.map(item => (
          <Box
            key={item}
            contentAlignment="center"
            modifiers={[size(160, 180), background('#3F51B5')]}>
            <Text color="#FFFFFF">{item}</Text>
          </Box>
        ))}
      </HorizontalUncontainedCarousel>
    </Host>
  );
}

API

import {
  HorizontalCenteredHeroCarousel,
  HorizontalMultiBrowseCarousel,
  HorizontalUncontainedCarousel,
} from '@expo/ui/jetpack-compose';

Components

`HorizontalCenteredHeroCarousel`

Android

Type: React.Element<ComponentType<HorizontalCenteredHeroCarouselProps>>

A hero carousel that centers one large item between two small peek items, matching Compose's HorizontalCenteredHeroCarousel.

Shared props across all carousel components.

HorizontalCenteredHeroCarouselProps

`maxItemWidth`

Android

Optional • Type: number

Maximum width of the hero item in dp. When unspecified, the hero item will be as wide as possible.

`maxSmallItemWidth`

Android

Optional • Type: number • Default: CarouselDefaults.MaxSmallItemSize

Maximum width of small peek items in dp.

`minSmallItemWidth`

Android

Optional • Type: number • Default: CarouselDefaults.MinSmallItemSize

Minimum width of small peek items in dp.

Inherited props

CarouselCommonConfig

`HorizontalMultiBrowseCarousel`

Android

Type: React.Element<ComponentType<HorizontalMultiBrowseCarouselProps>>

A carousel that shows a large item alongside smaller peek items, matching Compose's HorizontalMultiBrowseCarousel.

Shared props across all carousel components.

HorizontalMultiBrowseCarouselProps

`maxSmallItemWidth`

Android

Optional • Type: number • Default: CarouselDefaults.MaxSmallItemSize

Maximum width of small peek items in dp.

`minSmallItemWidth`

Android

Optional • Type: number • Default: CarouselDefaults.MinSmallItemSize

Minimum width of small peek items in dp.

`preferredItemWidth`

Android

Type: number

The preferred width of the large item in dp.

Inherited props

CarouselCommonConfig

`HorizontalUncontainedCarousel`

Android

Type: React.Element<ComponentType<HorizontalUncontainedCarouselProps>>

A carousel where each item has a fixed width with free-form scrolling, matching Compose's HorizontalUncontainedCarousel.

Shared props across all carousel components.

HorizontalUncontainedCarouselProps

`itemWidth`

Android

Type: number

The width of each item in dp.

Inherited props

CarouselCommonConfig

Types

`CarouselCommonConfig`

Android

Shared props across all carousel components.

Property	Type	Description
children	`React.ReactNode`	Children to render as carousel items.
contentPadding(optional)	`number \| PaddingValuesRecord`	Padding for carousel content (dp or object).
flingBehavior(optional)	`FlingBehaviorType`	Controls snapping behavior when the user flings the carousel. `'singleAdvance'` snaps to the next item, `'noSnap'` allows free scrolling.
itemSpacing(optional)	`number`	Spacing between items in dp. Default:`0`
modifiers(optional)	`ModifierConfig[]`	Modifiers for the component.
userScrollEnabled(optional)	`boolean`	Whether the user can scroll the carousel. Default:`true`

`FlingBehaviorType`

Android

Literal type: string

Fling behavior type for controlling carousel snapping.

Acceptable values are: 'singleAdvance' | 'noSnap'

`PaddingValuesRecord`

Android

Per-side padding values in dp for the content.

Property	Type	Description
bottom(optional)	`number`	-
end(optional)	`number`	-
start(optional)	`number`	-
top(optional)	`number`	-