swiper

更新时间：2023/03/13 访问次数：7584

一、简介
二、属性
三、事件
四、子节点事件
五、示例
六、FAQ

说明：本文档适用于小部件3.0。

一、简介

轮播组件

滑块视图容器，其子节点可以放置view，默认为横向滚动；

支持手淘版本：>= 10.5.20。

二、属性

属性	类型	描述	是否支持	将要支持
autoplay	Boolean	是否自动切换。默认值： false。	是	/
current	Number	当前页面的 index，可以增加左右箭头来控制轮播滚动。默认值： 0	是	/
duration	Number	滑动动画时长。默认值： 500(ms)。	否	是
interval	Number	自动切换时间间隔。默认值： 5000(ms)	是	/
circular	Boolean	是否启用无限滑动。默认值： false。	是（文档没有透出）	/
vertical	Boolean	滑动方向是否为纵向。默认值：false。	是	/
disable-programmatic-animation	Boolean	是否禁用swiper触发时使用动画默认值：false。	否	否
disable-touch	Boolean	是否禁止用户 touch 操作。默认值： false。	否	否
onChange	EventHandle	current 改变时会触发，event.detail = {current, isChanging}，其中 isChanging 需 acceleration 设置为 {{true}} 时才有值，当连续滑动多屏时，中间若干屏触发 onChange 事件时 isChanging 为 true，最后一屏返回 false。	是	/
onTransition	EventHandle	swiper 中 swiper-item 的位置发生改变时会触发 transition 事件。其中{dx,dy} = event.detail 开始支持。	否	否
indicator-dots	Boolean	是否显示指示点。默认值： false。	否（开发者可以自己实现）	否
indicator-color	Color	指示点颜色。默认值： rgba(0, 0, 0, .3)。	否	否
indicator-active-color	Color	当前选中的指示点颜色。默认值：#000。	否	否
active-class	String	swiper-item 可见时的 class。	否	否
changing-class	String	acceleration 设置为 {{true}} 时且处于滑动过程中，中间若干屏处于可见时的 class。	否	否
previous-margin	String	前边距，单位 px，1.9.0 暂时只支持水平方向。默认值： 0px。说明：去除 previous-margin 的设置距离可删除 swiper 组件左右空白距离。	否	否
next-margin	String	后边距，单位 px，1.9.0 暂时只支持水平方向。默认值： 0px。说明：去除 next-margin 的设置距离可删除 swiper 组件左右空白距离。	否	否
acceleration	Boolean	当开启时，会根据滑动速度，连续滑动多屏。默认值： false。	否	否
onAnimationEnd	EventHandle	动画结束时会触发 animationEnd 事件，event.detail = {current, source}，其中 source 的值有 autoplay 和 touch。	否	否
swipe-ratio	Number	滑动距离阈值，当滑动距离超过阈值时进行 swiper-item 切换。默认值：0.2。	否	否
swipe-speed	Number	滑动综合速度阈值，当超过阈值时进行 swiper-item 切换，数值越小越敏感。默认值：0.05。	否	否
touch-angle	Number	计算用户手势时所依赖的滑动角度。角度根据 touchstart 事件和首次 touchmove 事件的坐标计算得出。数值越小越对用户的滑动方向准确度要求越高。默认值：45。	否	否
display-multiple-items	Number	同时显示的滑块数量。默认值：1。	否	否
easing-function	String	切换缓动动画类型。默认值：default。	否	否
snap-to-edge	Boolean	当 swiper-item 个数大于等于 2，关闭 circular 并且开启 previous-margin 或 next-margin 时，可以指定这个边距是否应用到第一个、最后一个元素。默认值：false。	否	否
adjust-height	String	自动以指定滑块的高度为整个容器的高度。当 vertical 为 true 时，默认不调整。可选值为： first - 第一个滑块。 current - 实时的当前滑块。 highest - 高度最大的滑块。 none - 不根据滑块调整高度，容器高度取决于自身样式。默认值：first。	否	否
adjust-vertical-height	Boolean	vertical 为 true 时强制使 adjust-height 生效。默认值：false。	否	否

三、事件

onChange

类型： EventHandle。

描述：current改变时触发。

数据结构如下。

{
  detail: {
    current:0
  }
}

四、子节点事件

1. onAppear

类型： EventHandle。

描述：当前子节点即将出现在屏幕上时触发。

2. onDisappear

类型： EventHandle。

描述：当前子节点即将消失在屏幕上时触发。

五、示例

基本demo

/// test.axml
<view class="card-wrapper">
  <swiper class="swiper" interval="2000" circular="true" 
    current="{{currentIndex}}" autoplay="true" onChange="swiperChange">
    <view class="item" a:for="{{itemList}}" 
   onAppear="swiperItemAppear(item)" onDisappear="swiperItemDisappear(item)">
      <image class="item" src="{{item.pic}}"></image>
    </view>
  </swiper>
</view>
/// test.acss
.card-wrapper {
  width: 678rpx;
  height: 600rpx;
  border-radius: 3vw;
}
.swiper {
  width: 600rpx;
  height: 400rpx;
  border-width: 2rpx;
  border-color: cadetblue;
  border-style: solid;
}
.item {
  width: 600rpx;
  height: 400rpx;
}
/// test.js
Component({
  data: {
    currentIndex: 2,
    isAuto: false,
    itemList:[     
    {index:0, pic:'https://gd2.alicdn.com/bao/uploaded/i2/T14H1LFwBcXXXXXXXX_!!0-item_pic.jpg'},
    {index:1, pic: 'https://gd1.alicdn.com/bao/uploaded/i1/TB1PXJCJFXXXXciXFXXXXXXXXXX_!!0-item_pic.jpg'},
    {index:2, pic:  'https://gd3.alicdn.com/bao/uploaded/i3/TB1x6hYLXXXXXazXVXXXXXXXXXX_!!0-item_pic.jpg'},               
    {index:3, pic: 'https://img.alicdn.com/bao/uploaded/i1/2961083067/O1CN018X8ZGz1YWjMpghnHD_!!2961083067.jpg'},   
   ]
  },
  methods: {
    swiperChange(e) {
     console.log('-------> change:', e);
    },
    swiperItemAppear(e) {
      console.log('-------> item-appear:', e);
    },
    swiperItemDisappear(e) {
      console.log('-------> item-disappear:', e);
    },
  }
})

六、FAQ

1. appear事件，disappear事件正确使用方式

目前如果对swiper组件的子节点绑定apppear和disappear事件，其回调函数中返回数据默认是该节点的渲染相关数据，包括ref、styles、attributes等等，目前无法根据ref确定数据源中对应项。因此，推荐使用以下方式来绑定回调函数。

/// axml
<swiper class="swiper">
 <view class="item" a:for="{{itemList}}" 
   onAppear="swiperItemAppear(item)" onDisappear="swiperItemDisappear(item)">
   <image class="item" src="{{item.pic}}"></image>
 </view>
</swiper>
/// js
data: {
 itemList:[     
   {index:0, pic:'https://gd2.alicdn.com/bao/uploaded/i2/T14H1LFwBcXXXXXXXX_!!0-item_pic.jpg'},
   {index:1, pic: 'https://gd1.alicdn.com/bao/uploaded/i1/TB1PXJCJFXXXXciXFXXXXXXXXXX_!!0-item_pic.jpg'},
   {index:2, pic:  'https://gd3.alicdn.com/bao/uploaded/i3/TB1x6hYLXXXXXazXVXXXXXXXXXX_!!0-item_pic.jpg'},               
   {index:3, pic: 'https://img.alicdn.com/bao/uploaded/i1/2961083067/O1CN018X8ZGz1YWjMpghnHD_!!2961083067.jpg'},   
  ]
},
method: {
 swiperItemAppear(e) {
    /// e为itemList中对应项数据
  },
  swiperItemDisappear(e) {
    /// e为itemList中对应项数据
  }, 
}

2. Swiper组件子节点支持的组件

目前video、canvas、camera、input组件不支持作为子节点在swiper组件中使用，后续版本会支持。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

店铺动态卡片-开发指引

swiper

一、简介

二、属性

三、事件

onChange

四、子节点事件

1. onAppear

2. onDisappear

五、示例

基本demo

六、FAQ

1. appear事件，disappear事件正确使用方式

2. Swiper组件子节点支持的组件

FAQ