# @cleartrip/ct-design-3d-carousel 中文文档

规范地址：https://npmcn.com/package/%40cleartrip/ct-design-3d-carousel/

版本：5\.32\.0
npm 元数据更新时间：2026-11-16T13:03:38.396Z
中文译文更新时间：2026-11-16T13:07:29.404Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cleartrip/ct-design-3d-carousel
原文对照：https://npmcn.com/package/%40cleartrip/ct-design-3d-carousel/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：279 kB，42 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0，react-native \>=0\.68\.0，react-native-reanimated \>=3\.0\.0，react-native-gesture-handler \>=2\.0\.0
- 首次发布：2024-01-03T12:23:02.345Z
- 最新版本发布：2026-11-16T13:03:38.147Z
- 近 30 天下载量：16870（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1055（近 12 个月 672 个）

## 中文简介

动画木马相配器

## 安装

```sh
npm install @cleartrip/ct-design-3d-carousel
```

也可以使用：`pnpm add @cleartrip/ct-design-3d-carousel`、`yarn add @cleartrip/ct-design-3d-carousel`、`bun add @cleartrip/ct-design-3d-carousel`

## README

# 旋转木马3D

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

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

* * *

## 安装

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

### 同伴依赖关系

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

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

-   [恢复设置](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
-   [手势处理器设置](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation)

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

* * *

## 使用量

### 基础

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

### 带有导航图标

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

### 自动播放

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

### 带有自定义启动索引

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

### 自定义导航图标

```tsx
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`。 。 。 .

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

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

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

### 样式覆盖( 反应原生)

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

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

* * *

## 样式

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

```ts
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`\- 产生的风格.

### 完整实例

```tsx
// 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个位置布局:

| 职位 | `translateX` | `scale` |
| --- | --- | --- |
| 活动 | `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`

```diff
- import Carousel3D from 'yagami/core/components/components/3DCarousel';
+ import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
```

```diff
- 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 是什么？

动画木马相配器

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

