---
name: "swiper"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "swiper - 滑块视图容器"
---

## swiper

> [VERSION] 基础库 >= 2.10.0

### 描述

滑块视图容器，可用于轮播展示。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `indicator-dots` | `boolean` | 否 | `false` | 是否显示面板指示点 |
| `indicator-color` | `string` | 否 | `"rgba(0,0,0,0.3)"` | 指示点颜色 |
| `indicator-active-color` | `string` | 否 | `"#333"` | 当前选中的指示点颜色 |
| `vertical` | `boolean` | 否 | `false` | 滑动方向是否为纵向 |
| `autoplay` | `boolean` | 否 | `false` | 是否自动切换 |
| `circular` | `boolean` | 否 | `false` | 是否采用衔接滑动 |
| `interval` | `number` | 否 | `5000` | 自动切换时间间隔，单位毫秒 |
| `duration` | `number` | 否 | `500` | 滑动动画时长，单位毫秒 |
| `current` | `number` | 否 | `0` | 当前所在滑块的 index |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `change` | `(event: SwiperChangeEvent) => void` | current 改变时触发 |
| `animationfinish` | `(event: SwiperAnimationFinishEvent) => void` | 动画结束时触发 |

**SwiperChangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"change"` | 事件类型 |
| `detail` | `SwiperChangeDetail` | 事件数据 |

**SwiperAnimationFinishEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"animationfinish"` | 事件类型 |
| `detail` | `SwiperChangeDetail` | 事件数据 |

### 示例代码

#### 自动轮播与指示点

*index.tyml*

```xml
<swiper
  autoplay="{{true}}"
  circular="{{true}}"
  interval="{{3000}}"
  duration="{{500}}"
  indicator-dots="{{true}}"
  indicator-color="rgba(255,255,255,0.5)"
  indicator-active-color="#fff"
  class="swiper"
  bind:change="onChange"
>
  <swiper-item ty:for="{{list}}" ty:key="*this">
    <view class="item" style="background-color: {{item.color}};">
      <text class="item-text">{{item.text}}</text>
    </view>
  </swiper-item>
</swiper>
<text class="info">当前: {{current + 1}} / {{list.length}}</text>
```

*index.tyss*

```css
.swiper { height: 300rpx; }
.item {
  height: 300rpx;
  display: flex;
  align-items: center;
  justify-content: center;
}
.item-text { color: #fff; font-size: 36rpx; }
.info { display: block; text-align: center; margin-top: 16rpx; font-size: 28rpx; color: #666; }
```

*index.js*

```javascript
Page({
  data: {
    current: 0,
    list: [
      { text: '第一页', color: '#1890ff' },
      { text: '第二页', color: '#52c41a' },
      { text: '第三页', color: '#faad14' },
    ],
  },
  onChange(e) {
    this.setData({ current: e.detail.current });
  },
});
```

#### 纵向滑动与手动切换

*index.tyml*

```xml
<swiper
  vertical="{{true}}"
  current="{{current}}"
  indicator-dots="{{true}}"
  indicator-color="#ccc"
  indicator-active-color="#333"
  class="swiper"
  bind:animationfinish="onFinish"
>
  <swiper-item><view class="item item-a"><text>A</text></view></swiper-item>
  <swiper-item><view class="item item-b"><text>B</text></view></swiper-item>
  <swiper-item><view class="item item-c"><text>C</text></view></swiper-item>
</swiper>
<view class="btn-row">
  <button size="mini" bindtap="prev">上一页</button>
  <button size="mini" bindtap="next">下一页</button>
</view>
```

*index.tyss*

```css
.swiper { height: 400rpx; }
.item {
  height: 400rpx;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 48rpx;
  color: #fff;
}
.item-a { background-color: #1890ff; }
.item-b { background-color: #52c41a; }
.item-c { background-color: #faad14; }
.btn-row {
  display: flex;
  justify-content: center;
  gap: 20rpx;
  margin-top: 20rpx;
}
```

*index.js*

```javascript
Page({
  data: { current: 0 },
  prev() {
    var cur = this.data.current;
    this.setData({ current: cur > 0 ? cur - 1 : 2 });
  },
  next() {
    var cur = this.data.current;
    this.setData({ current: cur < 2 ? cur + 1 : 0 });
  },
  onFinish(e) {
    console.log('动画结束, 当前索引:', e.detail.current);
  },
});
```