‌核心属性‌

1. ‌data‌

   • 类型: Array<any>
   • 必填，轮播数据源，支持任意类型数据。

2. ‌renderItem‌

   • 类型: ({ item, index }) => React.ReactNode
   • 必填，自定义卡片渲染函数，参数包含当前项和索引。

3. ‌width/height‌

   • 类型: number
   • 控制轮播容器尺寸，默认填满父容器。

4. ‌loop‌

   • 类型: boolean
   • 是否启用无限循环滚动，默认true。

5. ‌autoPlay‌

   • 类型: boolean
   • 是否自动轮播，默认false。

6. ‌autoPlayInterval‌

   • 类型: number
   • 自动轮播间隔（毫秒），默认1000。

7. ‌mode‌

   • 类型: 'parallax' | 'horizontal-stack' | 'vertical-stack'
   • 轮播动画模式：视差效果/水平堆叠/垂直堆叠。

8. ‌modeConfig‌

   • 类型: object
   • 配合mode的详细参数，如视差偏移量(parallaxScrollingOffset)、缩放比例(parallaxScrollingScale)等。

9. ‌pagingEnabled‌

   • 类型: boolean
   • 是否启用分页滚动（一页一卡），默认true。

10. ‌snapEnabled‌

    • 类型: boolean
    • 是否启用吸附效果，滚动后自动对齐卡片，默认true。

---

‌核心方法（通过Ref调用）‌

1. ‌next()‌

   • 手动切换到下一张卡片。

2. ‌prev()‌

   • 手动切换到上一张卡片。

3. ‌scrollTo(index: number, animated?: boolean)‌

   • 跳转到指定索引的卡片，支持动画控制。

4. ‌getCurrentIndex()‌

   • 返回当前卡片的索引。

---

‌回调事件‌

1. ‌onSnapToItem(index: number)‌

   • 卡片切换完成时触发，返回当前索引。

2. ‌onProgressChange(progress: number, absoluteProgress: number)‌

   • 滚动进度变化时触发，用于自定义动画。

---

‌性能优化属性‌

1. ‌windowSize‌

   • 类型: number
   • 预渲染卡片数量（默认1），优化长列表性能。

2. ‌overscrollEnabled‌

   • 类型: boolean
   • 是否允许边界弹性滚动，默认true。

---

‌示例配置‌

<Carouselref={carouselRef}data={data}renderItem={renderItem}width={300}height={200}mode="parallax"modeConfig={{parallaxScrollingOffset: 50,parallaxScrollingScale: 0.9}}autoPlayautoPlayInterval={3000}onSnapToItem={(index) => console.log('当前索引:', index)}
/>

‌注意事项‌

1. 依赖react-native-reanimated@:ml-citation{ref="2" data="citationList"}.0.0，需正确配置babel插件。
2. 安卓需在MainActivity.java中启用Hermes引擎以获得最佳性能。
3. 复杂动画建议结合useAnimatedStyle实现。

---------------------------------------------------------------------------------------------------------------

关于modeConfig的模式配置

‌1. 视差模式（'parallax'）‌

• ‌parallaxScrollingOffset‌
  类型: number
  视差滚动偏移量，控制相邻卡片的间距（默认值通常为 100）
• ‌parallaxScrollingScale‌
  类型: number
  非中心卡片的缩放比例（默认 0.9，范围 0~1）
• ‌parallaxAdjacentItemScale‌
  类型: number
  相邻卡片的额外缩放比例（可选，进一步细化层级效果）

‌2. 水平堆叠模式（'horizontal-stack'）‌

• ‌stackInterval‌
  类型: number
  堆叠卡片之间的重叠间距（默认 8）
• ‌scaleInterval‌
  类型: number
  堆叠卡片的缩放递减梯度（默认 0.04）
• ‌opacityInterval‌
  类型: number
  堆叠卡片的透明度递减梯度（默认 0.1）

‌3. 垂直堆叠模式（'vertical-stack'）‌

• ‌stackInterval‌
  类型: number
  垂直方向的重叠间距（默认同水平模式）
• ‌translateYInterval‌
  类型: number
  垂直方向的位移偏移量（默认 20）

‌通用配置‌

• ‌showLength‌
  类型: number
  可见区域显示的卡片数量（仅部分模式支持）
• ‌rotateZDeg‌
  类型: number
  卡片的 3D 旋转角度（单位：度，需结合自定义样式使用）

‌示例配置‌

modeConfig={{parallaxScrollingOffset: 50,  // 视差偏移parallaxScrollingScale: 0.85, // 非中心卡片缩放stackInterval: 10,            // 堆叠间距opacityInterval: 0.2          // 透明度渐变
}}

不同模式需搭配对应的 mode 属性生效，且部分参数仅对特定模式有效