轮播

用于显示可滚动项目集合的 Jetpack Compose 轮播组件。

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~56.0.26

Expo UI 提供三个轮播组件，与官方 Jetpack Compose Carousel API 相匹配：HorizontalCenteredHeroCarousel、HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel。

注意： Carousel 是一个可水平滚动的组件，因此父级 Host 必须在滚动轴上提供一个有限宽度。请结合 style={{ width: '100%' }} 使用 matchContents={{ vertical: true }}（或任何有限宽度）。有关详细信息，请参见 Host 参考中的 Match contents。

安装

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 } 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), background(color)]}>
            <Text color="#FFFFFF">幻灯片 {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">卡片 {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 = ['照片 1', '照片 2', '照片 3', '照片 4', '照片 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.

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.

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.

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`	-