@cleartrip/ct-design-3d-carousel

中文文档
5.32.0发布于 2026/11/16ISCTypeScriptESM + CJS近 30 天下载 1.7万

Animated Carousel compoennt

原始使用文档
文档目录24 节
  1. Installation
  2. Peer dependencies
  3. Usage
  4. Basic
  5. With navigation icons
  6. With auto-play
  7. With a custom start index
  8. Custom navigation icons
  9. Style overrides (web)
  10. Style overrides (React Native)
  11. Props
  12. styleConfig
  13. Slots
  14. How styles are applied
  15. Full example
  16. Animation Details
  17. Web
  18. React Native
  19. Accessibility
  20. Styling Architecture
  21. Migration from yagami/core/components
  22. Breaking changes
  23. Changelog
  24. 2.21.0

Carousel3D

A perspective-based 3D card carousel that stacks slides in a fan layout — active slide centred and full size, adjacent slides scaled and offset to create depth.

Supports web (CSS transition-driven) and React Native (Reanimated v3-driven) from a single import.


Installation

npm install @cleartrip/ct-design-3d-carousel
# or
pnpm add @cleartrip/ct-design-3d-carousel

Peer dependencies

# Required for all targets
npm install react

# Web only
npm install react-dom

# React Native only
npm install react-native react-native-reanimated react-native-gesture-handler

Follow the official setup guides for Reanimated and GestureHandler:

Note: The native peer dependencies (react-native, react-native-reanimated, react-native-gesture-handler) are optional. Web-only projects do not need them.


Usage

Basic

import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';

function Example() {
  return (
    <Carousel3D height="300px" cardWidth="600px">
      <img src="/slide1.jpg" alt="Slide 1" />
      <img src="/slide2.jpg" alt="Slide 2" />
      <img src="/slide3.jpg" alt="Slide 3" />
    </Carousel3D>
  );
}

With navigation icons

<Carousel3D
  height="300px"
  cardWidth="600px"
  showSliderIcons
  onSlide={(index) => console.log('Active slide:', index)}
>
  {slides}
</Carousel3D>

With auto-play

<Carousel3D
  height="300px"
  cardWidth="600px"
  autoPlay
  autoPlaySpeed={2000}
  animationDelay={400}
>
  {slides}
</Carousel3D>

With a custom start index

// Start on the third slide (0-indexed)
<Carousel3D height="300px" cardWidth="600px" startIndex={2}>
  {slides}
</Carousel3D>

Custom navigation icons

import { MyLeftArrow, MyRightArrow } from './icons';

<Carousel3D
  height="300px"
  cardWidth="600px"
  showSliderIcons
  CustomLeftCarousalComponent={<MyLeftArrow />}
  CustomRightCarousalComponent={<MyRightArrow />}
>
  {slides}
</Carousel3D>

Style overrides (web)

Each styleConfig slot accepts an array of style objects. The styles are merged with the component's built-in static and dynamic styles via useWebMergeStyles from @cleartrip/ct-design-style-manager.

<Carousel3D
  height="300px"
  cardWidth="600px"
  styleConfig={{
    rootContainer: [{ backgroundColor: '#f5f5f5', padding: 24 }],
    sliderCardContainer: [{ borderRadius: 24 }],
  }}
>
  {slides}
</Carousel3D>

Multiple style objects can be composed in the array — later entries take precedence (same as React Native's StyleSheet array spreading):

<Carousel3D
  styleConfig={{
    rootContainer: [baseStyle, conditionalStyle, { marginTop: 16 }],
    sliderCardRootContainer: [overrideStyle],
  }}
>
  {slides}
</Carousel3D>

Style overrides (React Native)

The styleConfig shape is identical on native. Each slot accepts a Styles[] array and the entries are spread directly onto the View's style prop.

import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  card: { borderRadius: 24 },
  root: { backgroundColor: '#f5f5f5' },
});

<Carousel3D
  height={300}
  cardWidth="90%"
  styleConfig={{
    rootContainer: [styles.root],
    sliderCardContainer: [styles.card],
  }}
>
  {slides}
</Carousel3D>

Props

PropTypeDefaultRequiredDescription
childrenReactNode[]—✅Slides to display. Minimum 2, maximum 5 unique items (internally duplicated when ≤ 5).
heightstring | number—NoFixed height of the carousel frame (e.g. '300px' or 300).
cardWidthstring | number'100%'NoWidth of each card. Used to centre the carousel when narrower than the viewport.
startIndexnumber0NoIndex of the initially active slide.
animationDelaynumber480NoDuration (ms) of each slide transition animation.
showSliderIconsbooleanfalseNoShow left/right navigation chevron icons on the active slide.
CustomLeftCarousalComponentReactNode<LeftChevronWithBoundingBox />NoCustom element for the left navigation button.
CustomRightCarousalComponentReactNode<RightChevronWithBoundingBox />NoCustom element for the right navigation button.
autoPlaybooleanfalseNoEnable automatic slide cycling.
autoPlaySpeednumber900NoInterval (ms) between auto-play transitions.
onSlide(index: number) => void—NoCallback fired after each slide change. Receives the new active index.
styleConfigI3DCarouselStyleConfig—NoFine-grained style overrides for internal layout slots (see below).

styleConfig

styleConfig is a single unified interface used by both web and native. Every slot accepts a Styles[] array — the same pattern as React Native's style array spreading.

interface I3DCarouselStyleConfig {
  rootContainer?: Styles[];
  relativeBaseContainer?: Styles[];
  sliderRootContainer?: Styles[];
  iconsContainer?: Styles[];
  leftIconContainer?: Styles[];
  rightIconContainer?: Styles[];
  sliderCardContainer?: Styles[];
  sliderCardRootContainer?: Styles[];
}

Slots

SlotDescription
rootContainerOutermost flex wrapper
relativeBaseContainerRelative base that constrains the slide stack
sliderRootContainerAbsolute container holding all slide wrappers
iconsContainerOverlay for left/right navigation icons
leftIconContainerLeft icon wrapper
rightIconContainerRight icon wrapper
sliderCardContainerCard content container (shadow, borderRadius)
sliderCardRootContainerPer-slide absolute wrapper

How styles are applied

Web — each Styles[] entry is passed to useWebMergeStyles from @cleartrip/ct-design-style-manager, which converts raw style objects to Emotion class names and merges them with the component's built-in class names.

Native — each Styles[] entry is spread directly into the View's style array alongside the component's makeStyles-generated styles.

Full example

// Web
<Carousel3D
  height="300px"
  cardWidth="600px"
  styleConfig={{
    rootContainer: [{ backgroundColor: '#f0f4ff' }],
    relativeBaseContainer: [{ borderRadius: 16 }],
    sliderCardContainer: [{ borderRadius: 24, boxShadow: '0 8px 32px rgba(0,0,0,0.12)' }],
    sliderCardRootContainer: [{ overflow: 'hidden' }],
  }}
>
  {slides}
</Carousel3D>

// React Native
import { StyleSheet } from 'react-native';
const s = StyleSheet.create({
  root: { backgroundColor: '#f0f4ff' },
  card: { borderRadius: 24 },
});

<Carousel3D
  height={300}
  cardWidth="90%"
  styleConfig={{
    rootContainer: [s.root],
    sliderCardContainer: [s.card],
  }}
>
  {slides}
</Carousel3D>

Animation Details

Web

Animation is driven entirely by CSS transition on transform and opacity. When slideCurrent changes, React re-renders each CarouselSlide with new target transform values. The browser interpolates between states using the declared cubic-bezier(0.3, 0.46, 0.36, 0.93) easing and the animationDelay duration.

No @keyframes, no JS animation loop, no requestAnimationFrame. Smooth, composited, GPU-accelerated.

The 5-position layout:

PositiontranslateXscale
Active0%1.0
Pre-active (left-1)-18%0.75
Pro-active (right-1)+18%0.75
Pre-pre-active (left-2)-34%0.5
Pro-pro-active (right-2)+34%0.5
Hidden0%0.0

React Native

Animation is driven by Reanimated v3 — useSharedValue, withTiming, useAnimatedStyle. All animations run on the UI thread with no JS bridge round-trips.

Each slide owns five shared values (zIndex, translateX, translateY, scale, opacity). When slideCurrent changes, a useEffect fires and drives each value to its new target with withTiming(target, { duration: animationDelay, easing: Easing.inOut(Easing.ease) }).

Swipe gestures are handled by PanGestureHandler from react-native-gesture-handler. The gesture worklet bridges to React state via runOnJS.


Accessibility

  • Left/right navigation icons are wrapped in <Pressable> (native) or <Container role="button"> (web) with appropriate aria-label / accessibilityLabel.
  • Touch target for navigation icons: ensure icons are at least 44×44 pt.
  • Slide content should include alt attributes on images and appropriate ARIA for other content.
  • The component does not auto-announce slide changes to screen readers. Consider adding a visually hidden live region if your use case requires it.

Styling Architecture

Styles follow the design-system migration rules:

  • Static styles (never change) — defined at module level with makeStyles from @cleartrip/ct-design-style-manager. Processed through the design-system theme and emitted as Emotion class names (web) or style objects (native) at import time.
  • Dynamic styles (depend on props) — computed inside the component with useStyles. Re-run only when deps change.
  • Combined output (web) — merged into a single className string via useWebMergeStyles, passed to Container.
  • Combined output (native) — merged into a style array and spread onto View.
  • No @emotion/styled wrappers — all styled components have been removed.
  • No SCSS/CSS files — the previous index.scss (class-based animation) has been replaced by computed CSS via makeStyles.

Migration from yagami/core/components

- import Carousel3D from 'yagami/core/components/components/3DCarousel';
+ import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
- import Carousel3D from 'yagami/core/components/components/3DCarousel/index.native';
+ import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
  // Metro resolves .native.ts automatically

Breaking changes

AreaBefore (yagami)After (ct-design-system)
styleConfig shaperootContainerStyles?: Styles[] (native) / rootContainerProps?: { css?, className? } (web)rootContainer?: Styles[] — unified, same on both platforms
Key namingrootContainerProps (web) / rootContainerStyles (native)rootContainer — no Props / Styles suffix
SCSS importimport './index.scss' not required externallyNo CSS file to import — styles are bundled
Swipe (native)useSwipeable (internal Yagami hook)PanGestureHandler (gesture-handler)
Animation (native)Reanimated v3 ✅ (same)Reanimated v3 ✅

Changelog

2.21.0

  • Migrated from yagami/core/components/components/3DCarousel
  • Unified styleConfig — single I3DCarouselStyleConfig interface used on both web and native; all slot keys accept Styles[] arrays (e.g. rootContainer: [style1, style2])
  • Removed separate I3DCarouselNativeStyleConfig and IWebContainerStyleProps interfaces
  • Removed StyleSheet.create from native files; replaced with makeStyles from @cleartrip/ct-design-style-manager
  • Replaced @emotion/styled wrappers with makeStyles + useStyles + useWebMergeStyles
  • Removed index.scss (class-based CSS animations); replaced with CSS transition computed via makeStyles
  • Added full React Native implementation (Corousel3D.native.tsx + CarouselSlide.native.tsx) replacing the previous stub
  • Updated animation for native: Reanimated v3 throughout (useSharedValue, withTiming, useAnimatedStyle)
  • Updated swipe for native: PanGestureHandler from react-native-gesture-handler
  • Added react-native-reanimated + react-native-gesture-handler as optional peer dependencies
  • Normalised constants: unified CAROUSEL_CARD_CLASSNAMES between web and native

版本与发布记录

@cleartrip/ct-design-3d-carousel 共发布 1,055 个版本,首次发布于 2024/01/03;过去 12 个月发布了 672 个版本。

版本发布日期距今
5.32.0latest2026/11/16今天
5.32.0-SNAPSHOT-5.32.0-SNAPSHOT-bs-height-check-161120161537.02026/11/16今天
5.32.0-SNAPSHOT-bs-height-check-151120162243.02026/11/16今天
2.33.0-SNAPSHOT-hdp-revamp-v3.02026/11/124 天前
2.33.0-SNAPSHOT-hdp-revamp-v2.02026/11/124 天前
5.32.0-SNAPSHOT-biztrip-rn-sme-snapshot-11-11-26.02026/11/115 天前

其他发布通道:SNAPSHOT-3DCAROUSEL → 1.1.0-SNAPSHOT-3DCAROUSEL.0,SNAPSHOT-badgecarousel → 1.1.0-SNAPSHOT-badgecarousel.0,SNAPSHOT-carousel-spacer-badge → 1.1.0-SNAPSHOT-carousel-spacer-badge.1,SNAPSHOT-carousel-spacer-badge-calendar → 1.1.0-SNAPSHOT-carousel-spacer-badge-calendar.2,SNAPSHOT-carousel-spacer-badge-carousel → 1.1.0-SNAPSHOT-carousel-spacer-badge-carousel.1,SNAPSHOT-carousel-spacer → 1.1.0-SNAPSHOT-carousel-spacer.1。

关于 @cleartrip/ct-design-3d-carousel 的常见问题

@cleartrip/ct-design-3d-carousel 是什么?

Animated Carousel compoennt

如何安装 @cleartrip/ct-design-3d-carousel?

在项目目录运行 npm install @cleartrip/ct-design-3d-carousel,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)、react-dom(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@cleartrip/ct-design-3d-carousel 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@cleartrip/ct-design-3d-carousel 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@cleartrip/ct-design-3d-carousel 可以商用吗?

@cleartrip/ct-design-3d-carousel 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@cleartrip/ct-design-3d-carousel 的下载量有多少?

根据 npm 官方下载统计,@cleartrip/ct-design-3d-carousel 在 2026/10/10 – 2026/11/08 这 30 天内被下载 16,870 次,日均约 562 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@cleartrip/ct-design-3d-carousel 还在维护吗?

最新版本 5.32.0 发布于 2026/11/16(今天);至今共发布 1055 个版本,其中过去 12 个月发布了 672 个;首次发布于 2024/01/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。