旋转木马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 | 类型 | 默认 | 需求 | 说明 |
|---|---|---|---|---|
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相同的模式
土著风格阵列扩散.
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个位置布局:
| 职位 | 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
- 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介于网络和本地之间