@cleartrip/ct-design-3d-carousel

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

动画木马相配器

中文使用文档
文档目录24 节
  1. 安装
  2. 同伴依赖关系
  3. 使用量
  4. 基础
  5. 带有导航图标
  6. 自动播放
  7. 带有自定义启动索引
  8. 自定义导航图标
  9. 样式覆盖 (web)
  10. 样式覆盖( 反应原生)
  11. 道具
  12. 样式
  13. 槽数
  14. 样式如何应用
  15. 完整实例
  16. 动画细节
  17. 网页
  18. 原生反应
  19. 无障碍
  20. 样式建筑
  21. 从 yagami/core/components
  22. 中断更改
  23. 更改日志
  24. 2.21.0 (中文(简体) )

旋转木马3D

以视角为主的3D卡式旋转木马以扇形布局来叠放幻灯片——以活性幻灯片为中心并全尺寸,相邻幻灯片缩放并相抵以创造深度.

支助 网络 (预算外) transition- 驱动)和 原生反应 (重新命名为 v3 驱动) 从单一导入.


安装

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

同伴依赖关系

# 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

遵循重新激活和手腕汉德勒的官方设置指南:

说明: 本地同龄人依赖关系(react-native, (中文(简体) ), react-native-reanimated, (中文(简体) ), react-native-gesture-handler)是可选的。 只有网络的项目并不需要.


使用量

基础

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>
  );
}

带有导航图标

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

自动播放

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

带有自定义启动索引

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

自定义导航图标

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

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

样式覆盖 (web)

每个 styleConfig 槽接受一系列样式对象。 风格是 与组件的内置静态和动态样式通过 useWebMergeStyles 从 @cleartrip/ct-design-style-manager。 。 。 .

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

多个样式对象可以在数组中组成——以后的条目取用 优先级( 与 React Industrial 相同) StyleSheet 数组分布 :

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

样式覆盖( 反应原生)

这个 styleConfig 形状在本土是相同的。 每个槽接受一个 Styles[] 数组和条目直接分布到 View是因为 style 道具 (英语).

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>

道具

Prop类型默认需求说明
childrenReactNode[]—— 说✅要显示的幻灯片 。 最小2个,最大5个独有项目(内部复制于 5).
heightstring | number—— 说没有旋转木架的固定高度(例如. '300px' 或者说 300) (中文(简体) ).
cardWidthstring | number'100%'没有每张卡的宽度。 曾经在比取景口更窄时将旋转木马置于中心.
startIndexnumber0没有初始活动幻灯片索引 .
animationDelaynumber480没有每个幻灯片过渡动画的持续时间( ms).
showSliderIconsbooleanfalse没有在活动幻灯片上显示左/右导航切夫龙图标.
CustomLeftCarousalComponentReactNode<LeftChevronWithBoundingBox />没有左侧导航按钮自定义元素 .
CustomRightCarousalComponentReactNode<RightChevronWithBoundingBox />没有右键的自定义元素 .
autoPlaybooleanfalse没有启用自动滑行循环.
autoPlaySpeednumber900没有自动游戏过渡之间的间隔(ms).
onSlide(index: number) => void—— 说没有每次幻灯片更改后, 调用已启动 。 接收新的活动索引.
styleConfigI3DCarouselStyleConfig—— 说没有内部布局槽的精细纹饰样式覆盖(见下文).

样式

styleConfig 是用于 网络和本土。 。 。 . 每个槽接受一个 Styles[] 数组 - 和React相同的模式 土著风格阵列扩散.

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

槽数

槽说明
rootContainer最外侧的弹性包装
relativeBaseContainer限制幻灯片堆栈的相对基础
sliderRootContainer装有所有幻灯片包装的绝对容器
iconsContainer左/右导航图标的重叠
leftIconContainer左侧图标包
rightIconContainer右侧图标包装
sliderCardContainer卡片内容容器(阴影,边框Radius)
sliderCardRootContainer平滑绝对包

样式如何应用

网页 ——每个 Styles[] 条目通过 useWebMergeStyles 从 @cleartrip/ct-design-style-manager,将原始样式对象转换为 情感类名并和组件的内置类名合并.

土著 ——每个 Styles[] 条目直接分散到 View是因为 style 与组件相邻的数组 makeStyles- 产生的风格.

完整实例

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

动画细节

网页

动画完全由CSS驱动 transition 打开 transform 财务报告和审定财务报表 opacity时 slideCurrent 变化, 重播时每次重播 CarouselSlide 带有新目标转换值。 浏览器使用已声明的状态在状态间插入 cubic-bezier(0.3, 0.46, 0.36, 0.93) 放松和放松 animationDelay 持续时间.

没有 @keyframes没有JS动画循环,没有 requestAnimationFrame平滑,复合,GPU加速.

5个位置布局:

职位translateXscale
活动0%1.0
预用( 左-1)-18%0.75
主动(右-1)+18%0.75
预用(左-2)-34%0.5
主动(右-2)+34%0.5
隐藏0%0.0

原生反应

动画由 重新激活 v3 —— 说 useSharedValue, (中文(简体) ), withTiming, (中文(简体) ), useAnimatedStyle所有动画都运行在UI线上,没有JS桥回转.

每张幻灯片拥有5个共享值(zIndex, (中文(简体) ), translateX, (中文(简体) ), translateY, (中文(简体) ), scale, (中文(简体) ), opacity) (中文(简体) ). 何时 slideCurrent 变动,a useEffect 向新目标点火并驱动每个值 withTiming(target, { duration: animationDelay, easing: Easing.inOut(Easing.ease) })。 。 。 .

刷卡手势由 PanGestureHandler 从 react-native-gesture-handler。手势工作桥通过 runOnJS。 。 。 .


无障碍

  • 左右导航图标被包入 <Pressable> (本土)或 <Container role="button"> (网络) aria-label 编号 : accessibilityLabel。 。 。 .
  • 导航图标的触地目标:确保图标至少为44×44 pt.
  • 幻灯片内容应包括 alt 用于其他内容.
  • 组件不会自动对屏幕阅读器进行幻灯片修改 。 考虑在您需要的情况下, 添加一个视觉隐藏区域 .

样式建筑

样式遵循设计-系统迁移规则 :

  • 静态风格 (从未改变)——在模块一级与 makeStyles 从 @cleartrip/ct-design-style-manager。通过设计-系统主题进行处理,并在导入时作为情感类名称(web)或样式对象(native)发布.
  • 动态样式 (依赖道具)——在组件内计算 useStyles。仅在道具改变时重新运行.
  • 合并产出(网) ——合并为一 className 通过字符串 useWebMergeStyles,转至 Container。 。 。 .
  • 综合产出(本土) 合并为a style 数组并展开到 View。 。 。 .
  • 没有 @emotion/styled 包装 ——所有有样式的组件被删除.
  • 没有SCSS/CSS文件 - 上一个 index.scss (基于类的动画)已被计算 CSS 取而代之 makeStyles。 。 。 .

从 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

中断更改

区域在此之前(yagami(中文(简体) )之后(ct-design-system(中文(简体) )
styleConfig 形状rootContainerStyles?: Styles[] (内在) / rootContainerProps?: { css?, className? } (网络)rootContainer?: Styles[] ——统一,两个平台相同
密钥命名rootContainerProps (网络) / rootContainerStyles (内在)rootContainer 没有 Props 编号 : Styles 后缀
SCSS 导入import './index.scss' 外部需求没有要导入的 CSS 文件—— 样式被捆绑
刷子( 本地)useSwipeable (内部雅加米钩)PanGestureHandler (gesture - handler) (数字手)
动画(本土)重新激活 v3 (相同)重新激活 v3 QQ

更改日志

2.21.0 (中文(简体) )

  • 迁移 从 yagami/core/components/components/3DCarousel
  • 统一 styleConfig ——单身 I3DCarouselStyleConfig 用于网络和本地界面; 所有位键接受 Styles[] 阵列( 例如). rootContainer: [style1, style2](中文(简体) )
  • 删除 单独 I3DCarouselNativeStyleConfig 财务报告和审定财务报表 IWebContainerStyleProps 接口
  • 删除 StyleSheet.create 从本地文件; 替换为 makeStyles 从 @cleartrip/ct-design-style-manager
  • 已替换 @emotion/styled 包装带 makeStyles + 键 useStyles + 键 useWebMergeStyles
  • 删除 index.scss (基于类的 CSS 动画);被 CSS 所取代 transition 通过 makeStyles
  • 已添加 全面反应 原创执行Corousel3D.native.tsx + 键 CarouselSlide.native.tsx)替换了上个根
  • 更新 原生动画: 整个( )useSharedValue, (中文(简体) ), withTiming, (中文(简体) ), useAnimatedStyle(中文(简体) )
  • 更新 本地刷号 : PanGestureHandler 从 react-native-gesture-handler
  • 已添加 react-native-reanimated + 键 react-native-gesture-handler 作为可选同伴依赖关系
  • 正常化 常数: 统一 CAROUSEL_CARD_CLASSNAMES 介于网络和本地之间

版本与发布记录

@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 是什么?

动画木马相配器

如何安装 @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 和提交记录判断。