> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# swiper

轮播容器组件，支持自动播放、循环、自定义动画等功能。子节点须为 SwiperItem 组件。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=swiper"
  title="组件示例 swiper"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 swiper](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Fswiper%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>autoPlay</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否启用自动播放</td></tr>
<tr><td>autoPlayInterval</td><td><code>number</code></td><td>2000</td><td>否</td><td>自动播放间隔</td></tr>
<tr><td>blockNativeEvent</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否阻止原生事件</td></tr>
<tr><td>bounceConfig</td><td><code>BounceConfig</code></td><td>-</td><td>否</td><td>回弹参数配置</td></tr>
<tr><td>children</td><td><code>(prop: RenderFunctionProps&lt;T&gt;) =&gt; ReactElement</code></td><td>-</td><td>是</td><td>子元素，应该是一个函数，返回 SwiperItem</td></tr>
<tr><td>className</td><td><code>string</code></td><td>-</td><td>否</td><td>组件类名</td></tr>
<tr><td>consumeSlideEvent</td><td><code>[number, number][]</code></td><td>[[-180, -135], [-45, 45], [135, 180]]</td><td>否</td><td>决定 Swiper 如何响应不同角度的触摸</td></tr>
<tr><td>containerWidth</td><td><code>number</code></td><td>screenWidth</td><td>否</td><td>容器宽度</td></tr>
<tr><td>data</td><td><code>T[]</code></td><td>-</td><td>是</td><td>轮播图数据集合</td></tr>
<tr><td>duration</td><td><code>number</code></td><td>500</td><td>否</td><td>翻页或滑动动画的持续时间</td></tr>
<tr><td>initialIndex</td><td><code>number</code></td><td>0</td><td>否</td><td>初始索引，仅在首屏时使用，后续更新将被忽略</td></tr>
<tr><td>itemHeight</td><td><code>number | &quot;auto&quot;</code></td><td>-</td><td>否</td><td>轮播项高度</td></tr>
<tr><td>itemWidth</td><td><code>number</code></td><td>-</td><td>是</td><td>轮播项宽度</td></tr>
<tr><td>loop</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否开启循环轮播</td></tr>
<tr><td>loopDuplicateCount</td><td><code>number</code></td><td>2</td><td>否</td><td>当 loop 为 true 时，Swiper 会复制前 2 个和后 2 个项目来创建循环效果。<br>此属性可用于自定义复制第一个和最后一个项目的数量</td></tr>
<tr><td>main-thread:customAnimation</td><td><code>(value: number, index: number) =&gt; CSSProperties</code></td><td>-</td><td>否</td><td>自定义动画效果，应该是一个主线程函数</td></tr>
<tr><td>main-thread:easing</td><td><code>(progress: number) =&gt; number</code></td><td>-</td><td>否</td><td>自定义翻页效果的缓动函数</td></tr>
<tr><td>main-thread:onOffsetChange</td><td><code>(offset: number) =&gt; void</code></td><td>-</td><td>否</td><td>Swiper 偏移量改变时的回调函数，应该是一个主线程函数</td></tr>
<tr><td>mode</td><td><code>&quot;normal&quot; | &quot;custom&quot;</code></td><td>normal</td><td>否</td><td>Swiper 的模式。普通模式会使 SwiperItem 依次排列。<br>自定义模式会使 SwiperItem 以绝对定位方式放置在最左侧</td></tr>
<tr><td>modeConfig</td><td><code>{ align?: &quot;center&quot; | &quot;end&quot; | &quot;start&quot;; spaceBetween?: number } | Record&lt;string, unknown&gt;</code></td><td>-</td><td>否</td><td>模式的额外配置</td></tr>
<tr><td>offsetLimit</td><td><code>[number, number]</code></td><td>-</td><td>否</td><td>用于限制或扩展 Swiper 的偏移量范围，可用于限制偏移量以避免过度滚动</td></tr>
<tr><td>onChange</td><td><code>(current: number) =&gt; void</code></td><td>-</td><td>否</td><td>当前索引改变时的回调函数</td></tr>
<tr><td>onSwipeStart</td><td><code>(current: number) =&gt; void</code></td><td>-</td><td>否</td><td>开始滑动时的回调函数，可与 onSwipeStop 配合使用，用于在滑动时禁用点击事件</td></tr>
<tr><td>onSwipeStop</td><td><code>(current: number) =&gt; void</code></td><td>-</td><td>否</td><td>停止滑动时的回调函数，可与 onSwipeStart 配合使用</td></tr>
<tr><td>RTL</td><td><code>boolean | &quot;lynx-rtl&quot;</code></td><td>false</td><td>否</td><td>是否启用 RTL 模式</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>根元素样式，控制包含轮播图的可见视口/框架</td></tr>
</tbody>
</table>

## Ref 方法

<table>
<thead>
<tr><th width="180">方法名</th><th width="260">类型</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>cancelAnimation</td><td><code>() =&gt; void</code></td><td>取消当前正在运行的动画。谨慎使用，可能会破坏内部状态</td></tr>
<tr><td>swipeNext</td><td><code>() =&gt; void</code></td><td>滑动到下一个项目</td></tr>
<tr><td>swipePrev</td><td><code>() =&gt; void</code></td><td>滑动到上一个项目</td></tr>
<tr><td>swipeTo</td><td><code>(index: number, options?: SwipeToOptions) =&gt; void</code></td><td>滑动到指定索引的项目</td></tr>
</tbody>
</table>
