# swiper

> 基础库 1.0.0 开始支持，低版本需做[兼容处理](1003706)。

> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

滑块视图容器。其中只可放置[swiper-item](/miniprogram/dev/component/swiper-item)组件，否则会导致未定义的行为。

1. 使用 `worklet` 函数需要开启开发者工具 "将 JS 编译成 ES5" 或 "编译 worklet 函数" 选项。

## 通用属性


```json
[
  {
    "属性": "indicator-dots",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否显示面板指示点",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "indicator-color",
    "类型": "color",
    "默认值": "rgba(0, 0, 0, .3)",
    "必填": "否",
    "说明": "指示点颜色",
    "最低版本": "[1.1.0](1003706)"
  },
  {
    "属性": "indicator-active-color",
    "类型": "color",
    "默认值": "#000000",
    "必填": "否",
    "说明": "当前选中的指示点颜色",
    "最低版本": "[1.1.0](1003706)"
  },
  {
    "属性": "autoplay",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否自动切换",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "current",
    "类型": "number",
    "默认值": "0",
    "必填": "否",
    "说明": "当前所在滑块的 index",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "interval",
    "类型": "number",
    "默认值": "5000",
    "必填": "否",
    "说明": "自动切换时间间隔",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "duration",
    "类型": "number",
    "默认值": "500",
    "必填": "否",
    "说明": "滑动动画时长",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "circular",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否采用衔接滑动",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "vertical",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "滑动方向是否为纵向",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "display-multiple-items",
    "类型": "number",
    "默认值": "1",
    "必填": "否",
    "说明": "同时显示的滑块数量",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "previous-margin",
    "类型": "string",
    "默认值": "\"0px\"",
    "必填": "否",
    "说明": "前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "next-margin",
    "类型": "string",
    "默认值": "\"0px\"",
    "必填": "否",
    "说明": "后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值。skyline 于 3.5.1 版本支持",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "easing-function",
    "类型": "string",
    "默认值": "\"default\"",
    "必填": "否",
    "说明": "指定 swiper 切换缓动动画类型",
    "最低版本": "[2.6.5](1003706)",
    "子项": [
      {
        "合法值": "default",
        "说明": "默认缓动函数"
      },
      {
        "合法值": "linear",
        "说明": "线性动画"
      },
      {
        "合法值": "easeInCubic",
        "说明": "缓入动画"
      },
      {
        "合法值": "easeOutCubic",
        "说明": "缓出动画"
      },
      {
        "合法值": "easeInOutCubic",
        "说明": "缓入缓出动画"
      }
    ]
  },
  {
    "属性": "direction",
    "类型": "string",
    "默认值": "\"all\"",
    "必填": "否",
    "说明": "指定 swiper 滑动方向",
    "最低版本": "[3.8.10](1003706)",
    "子项": [
      {
        "合法值": "all",
        "说明": "默认"
      },
      {
        "合法值": "positive",
        "说明": "如 vertical 为 true 时，允许用户下滑（swiper 内容向上滚动），为 false 时，允许用户右滑（swiper 内容向左滚动）"
      },
      {
        "合法值": "negative",
        "说明": "如 vertical 为 true 时，允许用户上滑（swiper 内容向下滚动），为 false 时，允许用户左滑（swiper 内容向右滚动）"
      }
    ]
  },
  {
    "属性": "clip",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "是否对溢出进行裁剪",
    "最低版本": "[3.17.4](1003706)"
  },
  {
    "属性": "bind:change",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "current 改变时会触发 change 事件，event.detail = {current, source}",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:transition",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy}。Skyline 仅支持非 worklet 的组件方法作为回调。",
    "最低版本": "[2.4.3](1003706)"
  },
  {
    "属性": "bind:animationfinish",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "动画结束时会触发 animationfinish 事件，event.detail 同 bind:change。Skyline 仅支持非 worklet 的组件方法作为回调。",
    "最低版本": "[1.9.0](1003706)"
  }
]
```

## Skyline 特有属性


```json
[
  {
    "属性": "layout-type",
    "类型": "string",
    "默认值": "normal",
    "必填": "否",
    "说明": "渲染模式",
    "最低版本": "[3.2.0](1003706)",
    "子项": [
      {
        "合法值": "normal",
        "说明": "默认方式"
      },
      {
        "合法值": "stackLeft",
        "说明": "左向堆叠"
      },
      {
        "合法值": "stackRight",
        "说明": "右向堆叠"
      },
      {
        "合法值": "tinder",
        "说明": "滑动卡片"
      },
      {
        "合法值": "transformer",
        "说明": "过渡动画"
      }
    ]
  },
  {
    "属性": "transformer-type",
    "类型": "string",
    "默认值": "scaleAndFade",
    "必填": "否",
    "说明": "layout-type 为 transformer 时指定动画类型",
    "最低版本": "[3.2.0](1003706)",
    "子项": [
      {
        "合法值": "scaleAndFade",
        "说明": ""
      },
      {
        "合法值": "accordion",
        "说明": ""
      },
      {
        "合法值": "threeD",
        "说明": ""
      },
      {
        "合法值": "zoomIn",
        "说明": ""
      },
      {
        "合法值": "zoomOut",
        "说明": ""
      },
      {
        "合法值": "deepthPage",
        "说明": ""
      }
    ]
  },
  {
    "属性": "indicator-type",
    "类型": "string",
    "默认值": "normal",
    "必填": "否",
    "说明": "指示点动画类型",
    "最低版本": "[3.2.0](1003706)",
    "子项": [
      {
        "合法值": "normal",
        "说明": ""
      },
      {
        "合法值": "worm",
        "说明": ""
      },
      {
        "合法值": "wormThin",
        "说明": ""
      },
      {
        "合法值": "wormUnderground",
        "说明": ""
      },
      {
        "合法值": "wormThinUnderground",
        "说明": ""
      },
      {
        "合法值": "expand",
        "说明": ""
      },
      {
        "合法值": "jump",
        "说明": ""
      },
      {
        "合法值": "jumpWithOffset",
        "说明": ""
      },
      {
        "合法值": "scroll",
        "说明": ""
      },
      {
        "合法值": "scrollFixedCenter",
        "说明": ""
      },
      {
        "合法值": "slide",
        "说明": ""
      },
      {
        "合法值": "slideUnderground",
        "说明": ""
      },
      {
        "合法值": "scale",
        "说明": ""
      },
      {
        "合法值": "swap",
        "说明": ""
      },
      {
        "合法值": "swapYRotation",
        "说明": ""
      },
      {
        "合法值": "color",
        "说明": ""
      }
    ]
  },
  {
    "属性": "indicator-margin",
    "类型": "number",
    "默认值": "10",
    "必填": "否",
    "说明": "指示点四周边距",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-spacing",
    "类型": "number",
    "默认值": "4",
    "必填": "否",
    "说明": "指示点间距",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-radius",
    "类型": "number",
    "默认值": "4",
    "必填": "否",
    "说明": "指示点圆角大小",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-width",
    "类型": "number",
    "默认值": "8",
    "必填": "否",
    "说明": "指示点宽度",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-height",
    "类型": "number",
    "默认值": "8",
    "必填": "否",
    "说明": "指示点高度",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-alignment",
    "类型": "Array.<number>/string",
    "默认值": "auto",
    "必填": "否",
    "说明": "指示点的相对位置",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "indicator-offset",
    "类型": "Array.<number>",
    "默认值": "[0, 0]",
    "必填": "否",
    "说明": "指示点位置的偏移量",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "scroll-with-animation",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "改变 current 时使用动画过渡",
    "最低版本": "[2.29.0](1003706)"
  },
  {
    "属性": "cache-extent",
    "类型": "number",
    "默认值": "0",
    "必填": "否",
    "说明": "缓存区域大小，值为 1 表示提前渲染上下各一屏区域（swiper 容器大小）",
    "最低版本": "[2.29.0](1003706)"
  },
  {
    "属性": "worklet:onscrollstart",
    "类型": "worklet",
    "默认值": "",
    "必填": "否",
    "说明": "滑动开始时触发，仅支持 worklet 作为回调。event.detail = {dx: dx, dy: dy}",
    "最低版本": ""
  },
  {
    "属性": "worklet:onscrollupdate",
    "类型": "worklet",
    "默认值": "",
    "必填": "否",
    "说明": "滑动位置更新时触发，仅支持 worklet 作为回调。event.detail = {dx: dx, dy: dy}",
    "最低版本": ""
  },
  {
    "属性": "worklet:onscrollend",
    "类型": "worklet",
    "默认值": "",
    "必填": "否",
    "说明": "滑动结束时触发，仅支持 worklet 作为回调。event.detail = {dx: dx, dy: dy}",
    "最低版本": ""
  }
]
```

## WebView 特有属性


```json
[
  {
    "属性": "snap-to-edge",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "当 swiper-item 的个数大于等于 2，关闭 circular 并且开启 previous-margin 或 next-margin 的时候，可以指定这个边距是否应用到第一个、最后一个元素",
    "最低版本": "[2.12.1](1003706)"
  }
]
```

## 注意事项

1. `layout-type` 为 `stackLeft` `stackRight` 和 `tinder` 时仅支持 `indicator-type=normal`
2. `indicator-type` 为 `scrollFixedCenter` `swap` `swapYRotation` 无法在循环模式 `circular` 下使用
3. `indicator-alignment` 可指定为关键词 auto 或 长度为 2 的数组。
    - 横向滑动时 auto 相当于 bottomCenter [0, 1]
    - 纵向滑动时，auto 相当于 centerRight [1, 0]
    - 传入数组时，表示 x/y 轴的相对位置，取值范围 [-1, 1]，底边中点为 [0, 1]
4. `indicator-offset` 是长度为 2 的数组，表示指示点在 x/y 轴上的偏移量，单位 px。
5. skyline 的 `previous-margin`、 `display-multiple-items` 和 `vertical` 属性与 webview 表现略有不同，当skyline 使用 `next-margin` 属性且其值大于 0 时，会将前述三个属性对齐 webview 实现。

## 渲染模式效果演示

## 指示器效果演示

## Swiper 增强特性示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/2XhTe3m67uTb)

## `change`事件 `source` 返回值

从 [1.4.0](1003706) 开始，`change`事件增加 `source`字段，表示导致变更的原因，可能值如下：
1. `autoplay` 自动播放导致swiper变化；
2. `touch` 用户划动引起swiper变化；
3.  其它原因将用空字符串表示。

## Bug & Tip

1. `tip`: 如果在 `bind:change` 的事件回调函数中使用 `setData` 改变 `current` 值，则有可能导致 `setData` 被不停地调用，因而通常情况下请在改变 `current` 值前检测 `source` 字段来判断是否是由于用户触摸引起。
1. `tip`: 在 mac 小程序上，若当前组件所在的页面或全局开启了 `enablePassiveEvent` 配置项，该内置组件可能会出现非预期表现（详情参考 [enablePassiveEvent 文档](/miniprogram/dev/reference/configuration/app.md)）

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/mI88kSm57nJ9)