# swiper

基础库 1.0.0 开始支持,低版本需做兼容处理

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nighly 工具调试)、WebView

# 功能描述

滑块视图容器。其中只可放置swiper-item组件,否则会导致未定义的行为。

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

# 通用属性

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

# Skyline 特有属性

属性 类型 默认值 必填 说明 最低版本
layout-type string normal 渲染模式 3.2.0
合法值 说明
normal 默认方式
stackLeft 左向堆叠
stackRight 右向堆叠
tinder 滑动卡片
transformer 过渡动画
transformer-type string scaleAndFade layout-type 为 transformer 时指定动画类型 3.2.0
合法值 说明
scaleAndFade
accordion
threeD
zoomIn
zoomOut
deepthPage
indicator-type string normal 指示点动画类型 3.2.0
合法值 说明
normal
worm
wormThin
wormUnderground
wormThinUnderground
expand
jump
jumpWithOffset
scroll
scrollFixedCenter
slide
slideUnderground
scale
swap
swapYRotation
color
indicator-margin number 10 指示点四周边距 3.2.0
indicator-spacing number 4 指示点间距 3.2.0
indicator-radius number 4 指示点圆角大小 3.2.0
indicator-width number 8 指示点宽度 3.2.0
indicator-height number 8 指示点高度 3.2.0
indicator-alignment Array.<number>/string auto 指示点的相对位置 3.2.0
indicator-offset Array.<number> [0, 0] 指示点位置的偏移量 3.2.0
scroll-with-animation boolean true 改变 current 时使用动画过渡 2.29.0
cache-extent number 0 缓存区域大小,值为 1 表示提前渲染上下各一屏区域(swiper 容器大小) 2.29.0
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 特有属性

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

# 注意事项

  1. layout-typestackLeft stackRighttinder 时仅支持 indicator-type=normal
  2. indicator-typescrollFixedCenter 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-margindisplay-multiple-itemsvertical 属性与 webview 表现略有不同,当skyline 使用 next-margin 属性且其值大于 0 时,会将前述三个属性对齐 webview 实现。

# 渲染模式效果演示

# 指示器效果演示

# Swiper 增强特性示例代码

在开发者工具中预览效果

# change事件 source 返回值

1.4.0 开始,change事件增加 source字段,表示导致变更的原因,可能值如下:

  1. autoplay 自动播放导致swiper变化;
  2. touch 用户划动引起swiper变化;
  3. 其它原因将用空字符串表示。

# Bug & Tip

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

# 示例代码

在开发者工具中预览效果