# Swiper 滑块视图容器

[toc]

`Swiper` 组件常用于走马灯、轮播图等场景。目前仅支持`样式类名`、`图片链结`两种方式，暂不支持自定义滑块容器内容。

## 组件引入

在`app.json`或在页面`index.json`中引入：

```json
{
  "usingComponents": {
    "tea-swiper": "../dist/swiper/index"
  }
}
```

## 用法

### 基础用法

需要传入一个`swiperItems`的数组，数组的每一项是一个对象，对象属性详情见文档下方表格。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}"
/>
```

```javascript
Page({
  data: {
    // 方法一、 样式类名，通过 `class` 属性
    swiperItems: [
      {
        class: 'demo-1'
      }, 
      {
        class: 'demo-2'
      }, 
      {
        class: 'demo-3'
      }
    ], 

    // 方法二、 图片链结，通过 `imageUrl` 属性
    swiperItems: [
      {
        imageUrl: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/demo/1.png"
      }, 
      {
        imageUrl: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/demo/2.png"
      }, 
      {
        imageUrl: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/demo/3.png"
      }
    ]
  }
})
```

### 展示面板指示点

通过 `indicatorDots` 属性来展示面板指示点，可通过 `indicatorColor`、`indicatorActiveColor` 两个属性对指示点颜色与选中态颜色进行设置。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}" 
  indicatorDots="{{ true }}" 
  indicatorColor="#FFFFFF" 
  indicatorActiveColor="#006EFF"
/>
```

### 自动播放

通过 `autoplay` 属性来开启自动播放功能，可通过 `interval` 属性来设置自动切换时间间隔。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}" 
  autoplay="{{ true }}" 
  interval="{{ 7000 }}"
/>
```

### 衔接滑动

通过 `circular` 属性来开启衔接滑动效果。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}" 
  circular="{{ true }}"
/>
```

### 竖向滑动

通过 `vertical` 属性来设置竖向滑动效果。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}" 
  vertical="{{ true }}"
/>
```

### 元素边距

通过 `previousMargin`、`nextMargin` 属性来指定元素间距。

```html
<tea-swiper 
  swiperItems="{{ swiperItems }}" 
  previousMargin="30px" 
  nextMargin="30px"
/>
```

## Props

| 参数                   | 描述                                                 | 类型        | 默认值                 | 可选值                                                                      |
| -------------------- | -------------------------------------------------- | --------- | ------------------- | ------------------------------------------------------------------------ |
| indicatorDots        | 是否显示面板指示点                                          | `Boolean` | `false`             | -                                                                        |
| indicatorColor       | 指示点颜色                                              | `String`  | `rgba(0, 0, 0, .3)` | -                                                                        |
| indicatorActiveColor | 当前选中的指示点颜色                                         | `String`  | `#000000`           | -                                                                        |
| autoplay             | 是否自动切换                                             | `Boolean` | `false`             | -                                                                        |
| current              | 当前所在滑块的 index                                      | `Number`  | `0`                 | -                                                                        |
| interval             | 自动切换时间间隔                                           | `Number`  | `5000`              | -                                                                        |
| duration             | 滑动动画时长                                             | `Number`  | `500`               | -                                                                        |
| circular             | 是否采用衔接滑动                                           | `Boolean` | `false`             | -                                                                        |
| vertical             | 滑动方向是否为纵向                                          | `Boolean` | `false`             | -                                                                        |
| previousMargin       | 前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值                    | `String`  | `0px`               | -                                                                        |
| nextMargin           | 后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值                    | `String`  | `0px`               | -                                                                        |
| displayMultipleItems | 同时显示的滑块数量                                          | `Number`  | `1`                 | -                                                                        |
| skipHiddenItemLayout | 是否跳过未显示的滑块布局，设为 true 可优化复杂情况下的滑动性能，但会丢失隐藏状态滑块的布局信息 | `Boolean` | `false`             | -                                                                        |
| easingFunction       | 指定 swiper 切换缓动动画类型                                 | `String`  | `default`           | `['default', 'linear', 'easeInCubic', 'easeOutCubic', 'easeInOutCubic']` |
| swiperItems          | 滑块视图元素                                             | `Array`   | \`\`                | -                                                                        |
| hasArrow             | 是否显示箭头                                             | `Boolean` | `false`             | -                                                                        |

## 事件

| 事件名                  | 描述                                                                    | 回调参数 |
| -------------------- | --------------------------------------------------------------------- | ---- |
| bind:change          | current 改变时会触发 change 事件，event.detail = {current, source}             | -    |
| bind:transition      | swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy} | -    |
| bind:animationfinish | 动画结束时会触发 animationfinish 事件，event.detail = {dx: dx, dy: dy}           | -    |

## swiperItem

`Props`中的`swiperItem`为一个对象数组，数组中的每一个对象配置每一列，每一列有以下`key`：

| 键名       | 描述                 | 类型       | 默认值 |
| -------- | ------------------ | -------- | --- |
| class    | 样式类名               | `String` | -   |
| imageUrl | 图片链结，优先级高于 `class` | `String` | -   |

## 外部样式类

| 类名          | 描述       |
| ----------- | -------- |
| `ext-class` | 组件根节点样式类 |