category:
  en: Data Display
  zh-CN: 数据展示
icon: ''
extra: |
  ::: tip
    `list`为图片列表快捷设置，如果你需要自定义一些样式，或者内容并不为纯图片，可以引用`swiper-item`组件来自定义。
    <br>
    `list` 格式如下
    <br>

    ``` js
    [{
      url: 'javascript:',
      img: 'https://static.vux.li/demo/1.jpg',
      title: '送你一朵fua'
    }, {
      url: 'javascript:',
      img: 'https://static.vux.li/demo/5.jpg',
      title: '送你一次旅行',
      fallbackImg: 'https://static.vux.li/demo/3.jpg'
    }]
    ```

    `fallbackImg` 在 `v2.5.13` 支持，它将在 `img` 加载失败时显示，注意的是 `fallbackImg` 可能会在 `img` 加载成功时也进行了加载，只是不会显示（取决于浏览器实现）。

  :::

  ::: warning
  不要在`swiper`里嵌套`scroller`，在`web`上过于复杂化而且手势会有冲突，相关`Issue`将不会处理。
  <br>
  <br>
  该组件场景是固定高度的内容列表，不支持为不同 swiper-item 设置不同高度。
  <br>
  <br>
  如果确实需要设置不同高度，可以通过 ref 获取 swiper, 通过 this.$refs.swiper.xheight = '100px' 设置。 切记，需要放在 $nextTick 中执行。
  :::
tips:
  zh-CN:
    -
      q: swiper-item 只有两项时无法循环播放
      a: |
        是的，建议直接使用 `list` 来实现循环。因为实现原理是对`swiper-item`元素进行移动，需要至少有`3`个`swiper-item`才能保证有上一张和下一张可以切换。
props:
  list:
    type: Array
    en: image list, use swiper-item if you need to customize style
    zh-CN: 轮播图片列表，如果有自定义样式需求，请使用 swiper-item(使用 swiper-item 时仅有2个的情况下不支持循环)
  direction:
    type: String
    default: horizontal
    en: swiping direction
    zh-CN: 方向
  show-dots:
    type: Boolean
    default: true
    en: if show indicators
    zh-CN: 是否显示提示点
  show-desc-mask:
    type: Boolean
    default: true
    en: if show description mask
    zh-CN: 是否显示描述半透明遮罩
  dots-position:
    type: String
    default: right
    en: indicator position
    zh-CN: 提示点位置
  dots-class:
    en: custom indicator's classname
    zh-CN: 提示className
  auto:
    type: Boolean
    default: false
    en: if auto playing
    zh-CN: 是否自动轮播
  loop:
    type: Boolean
    default: false
    en: if use loop mode
    zh-CN: 是否循环
  interval:
    type: Number
    default: 3000
    en: interval value
    zh-CN: 轮播停留时长
  threshold:
    type: Number
    default: 50
    en: threshold value
    zh-CN: 当滑动超过这个距离时才滑动
  duration:
    type: Number
    default: 300
    en: transition duration
    zh-CN: 切换动画时间
  height:
    type: String
    default: 180px
    en: height value
    zh-CN: '高度值。如果为`100%`宽度并且知道宽高比，可以设置`aspect-ratio`自动计算高度'
  aspect-ratio:
    type: Number
    en: if specified, height will be caculated automatically
    zh-CN: 用以根据当前可用宽度计算高度值
  min-moving-distance:
    type: Number
    default: 0
    en: min distance before moving
    zh-CN: 超过这个距离时才滑动
  v-model:
    type: Number
    default: 0
    en: index value, use `v-model` for binding
    zh-CN: index 绑定，使用`v-model`，一般不需要绑定
events:
  on-index-change:
    params: '`(currentIndex)`'
    en: fires when index is changed
    zh-CN: 轮播 index 变化时触发
  on-get-height:
    version: v2.7.0
    params: '`(height)`'
    en: fires after height is caculated
    zh-CN: 高度获取后触发
changes:
  v2.9.2:
    en:
      - '[fix] fix stuck swipe after setting min-moving-distance #2773'
      - '[fix] fix error for repeat setting data in loop #2803'
    zh-CN:
      - '[fix] 修复设置最小移动距离后滑动卡住 #2773'
      - '[fix] 修复在循环模式下重复设置数据的错误 #2803'
  v2.7.7:
    en:
      - '[fix] fix cannot scroll body when touching with one item'
    zh-CN:
      - '[fix] 修复只有一个 item 时无法滚动页面的问题'
  v2.7.6:
    en:
      - '[enhance] stop moving width one item'
    zh-CN:
      - '[enhance] 只有一张图片时阻止滑动跟随'
  v2.7.0:
    en:
      - '[enhance] set shorter distance for first and last item for better experience'
      - '[feature] add event:on-get-height #2112'
      - '[enhance] stop interval if auto is set to false #2027'
    zh-CN:
      - '[enhance] 非循环模式下对第一张和最后一张使用更短的拖动距离'
      - '[feature] 添加事件 event:on-get-height #2112'
      - '[enhance] auto 支持动态设置 #2027'
  v2.6.0:
    en:
      - '[enhance] support fallbackImg for prop:list #1923'
    zh-CN:
      - '[enhance] 支持 list.fallbackImg 属性在图片加载失败时显示预设图片 #1923'
  v2.5.3:
    en:
      - '[fix] clear listTtwoLoopItem when list size !== 2 #1684 @weizs'
    zh-CN:
      - '[fix] 轮播个数不为2时清除 listTtwoLoopItem 列表 #1684 @weizs'
  v2.5.1:
    en:
      - '[fix] Fix array-from issue with webpack@3 #1649'
    zh-CN:
      - '[fix] 修复 array-from 在 webpack@3 下报错问题 #1649'
  v2.3.5:
    en:
      - '[fix] Fix repeat render bug #1458'
    zh-CN:
      - '[fix] 修复重复渲染问题 #1458'
  v2.3.4:
    en:
      - '[fix] Fix click to fail when only two swiper-item and loop #1484 @unclay'
    zh-CN:
      - '[fix] 修复只有两个轮播图且为 loop 时点击失效问题 #1484 @unclay'
  v2.2.1-rc.2:
    en:
      - '[enhance] Use document width as swiper width if initial width is 0 #1188'
      - '[fix] Fix initial index > 0 not works'
    zh-CN:
      - '[enhance] 如果初始化时获取不到宽度则直接使用视口宽度 #1188'
      - '[fix] 修复初始化时 index > 0 不生效'
  v2.1.1-rc.3:
    en:
      - '[fix] Fix nodes list forEach function is undefined #991 @howyhuang'
    zh-CN:
      - '[fix] 修复 node 列表没有 forEach 方法 #991 @howyhuang'
  v2.1.1-rc.2:
    en:
      - '[fix] Fix es6 iterator compability, use forEach'
    zh-CN:
      - '[fix] 修复部分机子不支持 for of 遍历'