| name | required | default | types | description |
|---|---|---|---|---|
| data | ✅ | T[] | 即将渲染的数据集合 | |
| renderItem | ✅ | (info: { item: T, index: number, animationValue: SharedValue<number> }) => React.ReactElement | 渲染元素的方法 | |
| defaultScrollOffsetValue | ❌ | useSharedValue(0) | boolean | 轮播图的默认动画值 |
| autoFillData | ❌ | true | boolean | 将会在loop属性设置为 true 时，自动填充 data 元素以满足 loop 循环效果([1] => [1, 1, 1]；[1, 2] => [1, 2, 1, 2]) |
| vertical | ❌ | false | boolean | 将元素垂直布局而不是水平 |
| width | 垂直时 ❌ 水平时 ✅ | '100%' | number | undefined | 指定每一项的宽度 |
| height | 垂直时 ✅ 水平时 ❌ | '100%' | number | undefined | 指定每一项的高度 |
| mode | ❌ | defalut | 'horizontal-stack'|'vertical-stack'|'parallax' | 轮播图播放模式 |
| modeConfig | ❌ | 不同 mode 对应不同配置，详情见下方[modeConfig](#modeConfig Props) |
||
| style | ❌ | {} | ViewStyle | 轮播图容器样式 |
| defaultIndex | ❌ | 0 | number | 默认 index |
| autoPlay | ❌ | false | boolean | 是否自动播放 |
| autoPlayReverse | ❌ | false | boolean | 是否倒序自动播放 |
| autoPlayInterval | ❌ | 1000 | number | 自动播放的间隔 |
| scrollAnimationDuration | ❌ | 500 | number | 滚动动画完成所需的时间 |
| loop | ❌ | true | boolean | 是否循环播放 |
| testID | ❌ | string | 在 E2E 测试中用来定位视图 | |
| onSnapToItem | ❌ | (index: number) => void | 切换至另一张轮播图时触发 | |
| onScrollBegin | ❌ | () => void | 切换动画开始时触发 | |
| onScrollEnd | ❌ | (index: number) => void | 切换动画结束时触发 | |
| withAnimation | ❌ | {type: 'spring';config: WithSpringConfig;} | {type: 'timing';config: WithTimingConfig;} | 指定滚动时的动画效果 | |
| panGestureHandlerProps | ❌ | {} | Omit<Partial<PanGestureHandlerProps>,'onHandlerStateChange'> | PanGestureHandler props |
| windowSize | ❌ | 0 | number | 能响应平移手势事件的最大 item 数量，0 表示所有元素都会先响应 |
| onProgressChange | ❌ | onProgressChange?: (offsetProgress: number,absoluteProgress: number) => void | 当滚动进度发生变化时触发 offsetProgress:总的偏移值 (0 390 780 ...); absoluteProgress:转化为 index 的进度变化 (0 1 2 ...) |
|
| modeConfig | ❌ | { snapDirection: 'left',moveSize: window.width,stackInterval: 30,scaleInterval: 0.08,rotateZDeg: 135} | {moveSize?: number;stackInterval?: number;scaleInterval?: number;rotateZDeg?: number;snapDirection?: 'left' | 'right';} | 堆栈视图的动画样式 |
| showLength | ❌ | data.length - 1 | number | 堆栈视图中展示元素的最大数量 |
| pagingEnabled | ❌ | true | boolean | 当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置。 |
| snapEnabled | ❌ | true | boolean | 如果启用，松开触摸会滚动到最近的元素，当 pagingEnabled=false 时有效 |
| enabled | ❌ | true | boolean | 当值为 false 时，轮播图将不会响应任何手势行为 |
| customConfig | ❌ | () => {type?: 'negative' | 'positive';viewCount?: number;} | 自定义轮播图内部配置 | |
| customAnimation | ❌ | (value: number) => Animated.AnimatedStyleProp | 自定动画，详情见自定义动画 |
| name | required | default | types | description |
|---|---|---|---|---|
| parallaxScrollingOffset | ❌ | 100 | number | 控制两侧图片离中间元素的距离 |
| parallaxScrollingScale | ❌ | 0.8 | number | 控制前面/当前/后面图片的缩放比例 |
| parallaxAdjacentItemScale | ❌ | parallaxAdjacentItemScale || Math.pow(parallaxScrollingScale, 2) | number | 控制前面/后面图片的缩放比例 |
| name | required | default | types | description |
|---|---|---|---|---|
| showLength | ❌ | data.length-1 | number | 展示数量 |
| moveSize | ❌ | screen.width | number | 移动距离 |
| stackInterval | ❌ | 18 | number | 间隔距离 |
| scaleInterval | ❌ | 0.04 | number | 每一个元素缩放的间隔 |
| opacityInterval | ❌ | 0.1 | number | 每一个元素透明度的间隔 |
| rotateZDeg | ❌ | 30 | number | 旋转角度 |
| snapDirection | ❌ | 'left' | 'left'|'right' | 图片滑动方向 |
| name | types | description |
|---|---|---|
| prev | ({ count: number, animated: boolean, onFinished?: () => void }) => void | 切换至上一项，可以指定count决定切换的数量 |
| next | ({ count: number, animated: boolean, onFinished?: () => void }) => void | 切换至下一张，可以指定count决定切换的数量 |
| scrollTo | ({ index: number, count: number, animated: boolean, onFinished?: () => void }) => void | 切换到距离当前相对位置为count的位置，scrollTo({count:-2})等价于prev(2)，scrollTo({count:2})等价于next(2). 同样可以跳转到指定位置 scrollTo({index:2,animated:false}) |
| getCurrentIndex | ()=>number | 获得当前轮播图下标 |