旋转木马

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

Android

Included in Expo Go

Recommended version:

~57.0.3

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

🌐 Expo UI provides three carousel components matching the official Jetpack Compose Carousel API: HorizontalCenteredHeroCarousel, HorizontalMultiBrowseCarousel, and HorizontalUncontainedCarousel.

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

Material 3 multi-browse carousel with a hero item and smaller peek items

安装

🌐 Installation

Terminal

- npx expo install @expo/ui

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

用法

🌐 Usage

HorizontalCenteredHeroCarousel

将一个大英雄项目置于两个小预览项目之间——非常适合高亮电影海报等内容。

🌐 Centers one large hero item between two small peek items — ideal for spotlighting content like movie posters.

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">Slide {index + 1}</Text>
          </Box>
        ))}
      </HorizontalCenteredHeroCarousel>
    </Host>
  );
}

HorizontalMultiBrowseCarousel

显示大型项目及较小的预览项目，让用户浏览接下来内容。

🌐 Shows a large item alongside smaller peek items, letting users browse what comes next.

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

每个项目都有固定宽度，并且可以自由滚动。

🌐 Each item has a fixed width with free-form scrolling.

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`

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`

Optional • Type: number

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

`maxSmallItemWidth`

Optional • Type: number • Default: CarouselDefaults.MaxSmallItemSize

Maximum width of small peek items in dp.

`minSmallItemWidth`

Optional • Type: number • Default: CarouselDefaults.MinSmallItemSize

Minimum width of small peek items in dp.

Inherited Props

CarouselCommonConfig

`HorizontalMultiBrowseCarousel`

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`

Optional • Type: number • Default: CarouselDefaults.MaxSmallItemSize

Maximum width of small peek items in dp.

`minSmallItemWidth`

Optional • Type: number • Default: CarouselDefaults.MinSmallItemSize

Minimum width of small peek items in dp.

`preferredItemWidth`

Type: number

The preferred width of the large item in dp.

Inherited Props

CarouselCommonConfig

`HorizontalUncontainedCarousel`

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`

Type: number

The width of each item in dp.

Inherited Props

CarouselCommonConfig

Types

`CarouselCommonConfig`

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`

Literal Type: string

Fling behavior type for controlling carousel snapping.

Acceptable values are: 'singleAdvance' | 'noSnap'

`PaddingValuesRecord`

Per-side padding values in dp for the content.

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