swiper 滑块视图容器

解释:滑块视图容器。内部只允许使用<swiper-item>组件描述滑块内容,否则会导致未定义的行为。

# 属性说明

属性名 类型 默认值 必填 说明 最低版本
indicator-dots Boolean false 是否显示面板指示点 -
indicator-color Color rgba(0, 0, 0, .3) 指示点颜色 -
indicator-active-color Color #333 当前选中的指示点颜色 -
autoplay Boolean false 是否自动切换 -
current Number 0 当前所在页面的 index -
current-item-id String 当前所在滑块的 item-id,不能与 current 被同时指定 1.11
低版本请做兼容性处理
interval Number 5000 自动切换时间间隔,单位 ms -
duration Number 500 滑动动画时长,单位 ms -
circular Boolean false 是否采用衔接滑动 -
vertical Boolean false 滑动方向是否为纵向 -
previous-margin String "0px" 前边距,可用于露出前一项的一小部分,支持 px 和 rpx 1.11
低版本请做兼容性处理
next-margin String "0px" 后边距,可用于露出后一项的一小部分,支持 px 和 rpx 1.11
低版本请做兼容性处理
display-multiple-items Number 1 同时显示的滑块数量 1.11
低版本请做兼容性处理
bindchange EventHandle current 改变时会触发 change 事件,event.detail = {current: current, source: source} -
bindanimationfinish EventHandle 动画结束时会触发 animationfinish 事件,event.detail 同上 1.11
低版本请做兼容性处理

# change 事件 source 返回值

change 事件中的 source 字段,表示触发 change 事件的原因,可能值如下:

说明
autoplay 自动播放导致的 swiper 切换
touch 用户划动导致的 swiper 切换
"" 其他原因将返回空字符串

# 示例

扫码体验
重新加载
请使用百度APP扫码

# 代码示例 :滑块滑动

    <view class="wrap">
        <view class="card-area">
            <swiper 
                class="swiper"
                indicator-dots="{{switchIndicateStatus}}" 
                indicator-color="rgba(0,0,0,0.30)"
                indicator-active-color="#fff"
                autoplay="{{switchAutoPlayStatus}}"
                current="0"
                current-item-id="0"        
                interval="{{autoPlayInterval}}"
                duration="{{switchDuration}}"
                circular="true"
                vertical="{{switchVerticalStatus}}"
                previous-margin="0px"
                next-margin="0px"
                display-multiple-items="1"
                bind:change="swiperChange"
                bind:animationfinish="animationfinish">
                <swiper-item 
                    s-for="item in items"
                    item-id="{{itemId}}"
                    class="{{item.className}}">
                    <view class="item">{{item.value}}</view>
                </swiper-item>
            </swiper>
    
            <view class="item-scroll border-bottom">
                <text class="switch-text-before">指示点</text>
                <switch 
                    class="init-switch" 
                    checked="{{switchIndicateStatus}}"
                    bind:change="switchIndicate">
                </switch>
            </view>
    
            <view class="item-scroll border-bottom">
                <text class="switch-text-before">自动切换</text>
                <switch 
                    checked="{{switchAutoPlayStatus}}" 
                    bind:change="switchAutoPlay" 
                    class="init-switch">
                </switch>
            </view>
    
            <view class="item-scroll">
                <text class="switch-text-before">纵向滑动</text>
                <switch 
                    checked="{{switchVerticalStatus}}" 
                    bind:change="switchVertical" 
                    class="init-switch">
                </switch>
            </view>
        </view>
        <view class="card-area">
            <view class="top-description border-bottom">
                <view>滑块切换时长</view>
                <view>{{switchDuration}}ms</view>
            </view>
            <slider 
                class="slider" 
                min="300" 
                max="1500" 
                value="{{switchDuration}}"
                bind:change="changeSwitchDuration">
            </slider>
        </view>
        <view class="card-area">
            <view class="top-description border-bottom">
                <view>自动切换时间间隔</view>
                <view>{{autoPlayInterval}}ms</view>
            </view>
            <slider 
                class="slider" 
                min="1000" 
                max="5000" 
                value="{{autoPlayInterval}}"
                bind:change="changeAutoPlayInterval">
            </slider>
        </view>
    </view>
    
    Page({
        data: {
            items: [
                {
                    className: 'color-a',
                    value: 'A'
                }, {
                    className: 'color-b',
                    value: 'B'
                }, {
                    className: 'color-c',
                    value: 'C'
                }
            ],
            current: 0,
            itemId: 0,
            switchIndicateStatus: true,
            switchAutoPlayStatus: false,
            switchVerticalStatus: false,
            switchDuration: 500,
            autoPlayInterval: 2000
        },
        swiperChange(e) {
            console.log('swiperChange:', e.detail);
            this.setData({
                itemId: e.detail.current
            });
        },
        switchIndicate() {
            this.setData({
                switchIndicateStatus: !this.getData('switchIndicateStatus')
            });
        },
        switchVertical() {
            this.setData({
                switchVerticalStatus: !this.getData('switchVerticalStatus')
            });
        },
        switchAutoPlay() {
            this.setData({
                switchAutoPlayStatus: !this.getData('switchAutoPlayStatus')
            });
        },
        changeSwitchDuration(e) {
            this.setData({
                switchDuration: e.detail.value
            });
        },
        changeAutoPlayInterval(e) {
            this.setData({
                autoPlayInterval: e.detail.value
            });
        },
        animationfinish(e) {
            console.log(e.type);
        }
    });
    
    .swiper {
        height: 2.18rem;
        border-radius: 8px 8px 0 0;
    }
    
    .item {
        width: 100%;
        height: 2.18rem;
        font-size: .18rem;
        color: #fff;
        text-align: center;
        line-height: 2.18rem;
    }
    
    .slider {
        margin: .3rem .23rem;
    }
    
    .switch-text-before {
        margin-top: .17rem;
    }
    
    .init-switch {
        vertical-align: middle;
        margin: .14rem 0 .14rem .17rem;
    }
    
    .color-a {
        background-color: #5B9FFF;
    }
    
    .color-b {
        background-color: #85B8FF;
    }
    
    .color-c {
        background-color: #ADCFFF;
    }
    
    .switch {
        position: absolute;
        top: 50%;
        right: 0;
        transform: translateY(-50%);
    }
    

    设计指南

    DESIGN

    建议滑块视图数量控制在 2-5 个。
    建议滑块切换时长不低于 500ms,自动切换时间间隔不高于 5000ms。

    # Bug & Tip

    • Tip:如果在 bindchange 的事件回调函数中使用 setData 改变 current 值,则会导致 setData 被重复调用,因而通常情况下请在改变 current 值前检测 source 字段来判断是否是由于用户触摸引起的。
    • Tip:其中只可放置 swiper-item 组件,否则会导致未定义的行为。

    # 参考示例

    # 参考示例 1:用于实现顶部标签切换

      <view class="container"> 
          <!-- 顶部导航 -->
          <view class="swiper-tab">
              <view class="tab-item {{currentTab==0 ? 'on' : ''}}" data-current="0" bindtap="swiperNav">Tab1</view> 
              <view class="tab-item {{currentTab==1 ? 'on' : ''}}" data-current="1" bindtap="swiperNav">Tab2</view>
              <view class="tab-item {{currentTab==2 ? 'on' : ''}}" data-current="2" bindtap="swiperNav">Tab3</view>
          </view>
          <!-- 顶部导航对应的内容 -->
          <swiper class="swiper" current="{{currentTab}}" duration="200" bindchange="swiperChange">
              <swiper-item>   
                  <!-- 页面可使用自定义组件编写 -->
                  <view>我是tab1</view>   
              </swiper-item>
              <swiper-item>
                  <view>我是tab2</view>
              </swiper-item> 
              <swiper-item>
                  <view>我是tab3</view>
              </swiper-item>
          </swiper>
      </view>
      
      Page({
          data: {
              currentTab: 0,
          },
          swiperNav(e) {
              console.log(e); 
             
              if (this.data.currentTab === e.target.dataset.current) {
                  return false;
              } else {
                  this.setData({ 
                      currentTab: e.target.dataset.current, 
                  })
              }
          },
          swiperChange: function (e) {
              console.log(e);  
              this.setData({
                  currentTab: e.detail.current, 
              })
          }
      })
      
      .swiper-tab {
          display: flex;
          flex-direction: row;
          line-height: 80rpx;
          border-bottom: 1rpx solid #f5f5f5;
      }
      
      .tab-item {
          width: 33.3%;
          text-align: center; 
          font-size: .16rem;
          color: rgb(116, 113, 113);
      }
      
      .swiper {
          height: 1100px; 
          background: #dfdfdf;
      }
      
      .on {
          color: #5B9FFF;
          border-bottom: 1px solid #5B9FFF;
          padding-bottom: 2px
      }
      

      # 参考示例 2: 自定义底部切换圆点

        <view class="swiper-wrap">
            <swiper autoplay="auto" interval="5000" duration="500" current="{{swiperCurrent}}" bindchange="swiperChange" class="swiper">
                <swiper-item s-for="{{slider}}">
                    <image src="{{item.imageUrl}}" class="img"></image>
                </swiper-item>
            </swiper>
            
            <view class="dots">
                <view s-for="{{slider}}" class="dot {{index == swiperCurrent ? ' active' : ''}}"></view>
            </view>
        </view>
        
        Page({
            data: {
                slider: [{
                    imageUrl: 'https://b.bdstatic.com/miniapp/image/hypnosis.jpeg'
                }, {
                    imageUrl: 'https://b.bdstatic.com/miniapp/images/hypnosis.jpeg'
                }, {
                    imageUrl: 'https://b.bdstatic.com/miniapp/image/airCaptain.jpeg'
                }],
                swiperCurrent: 0
            },
            swiperChange(e) {
                this.setData({
                    swiperCurrent: e.detail.current
                })
            }
        })
        
        .swiper-wrap{
            position: relative;
        }
        .swiper-wrap .swiper{
            height: 300rpx;
        }
        .swiper-wrap .swiper .img{
            width: 100%;
            height: 100%;
        }
        .swiper-wrap .dots{
            position: absolute;
            right: 20rpx;
            bottom: 20rpx;
            display: flex;
            justify-content: center;
        }
        .swiper-wrap .dots .dot{
            margin: 0 8rpx;
            width: 14rpx;
            height: 14rpx;
            background: #fff;
            border-radius: 8rpx;
            transition: all .6s;
        }
        
        .swiper-wrap .dots .dot.active{
            width: 24rpx;
            background: #38f;
        }
        

        # 常见问题

        # Q:swiper 的面板指示点能自定义样式吗

        A: 参见属性说明,可以去 dot 显示之后,自己定义 dot 样式。

        代码示例: 参考示例 2