swiper
基礎(chǔ)庫 1.0.0 開始支持，低版本需做兼容處理。
微信 Windows 版：支持
微信 Mac 版：支持
微信 鴻蒙 OS 版：支持
渲染框架支持情況：Skyline （使用最新 Nightly 工具調(diào)試）、WebView
功能描述
滑塊視圖容器。其中只可放置swiper-item組件，否則會(huì)導(dǎo)致未定義的行為。
- 使用
worklet 函數(shù)需要開啟開發(fā)者工具 "將 JS 編譯成 ES5" 或 "編譯 worklet 函數(shù)" 選項(xiàng)。
通用屬性
| 屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 | 最低版本 |
|---|
| indicator-dots | boolean | false | 否 | 是否顯示面板指示點(diǎn) | 1.0.0 |
| indicator-color | color | rgba(0, 0, 0, .3) | 否 | 指示點(diǎn)顏色 | 1.1.0 |
| indicator-active-color | color | #000000 | 否 | 當(dāng)前選中的指示點(diǎn)顏色 | 1.1.0 |
| autoplay | boolean | false | 否 | 是否自動(dòng)切換 | 1.0.0 |
| current | number | 0 | 否 | 當(dāng)前所在滑塊的 index | 1.0.0 |
| interval | number | 5000 | 否 | 自動(dòng)切換時(shí)間間隔 | 1.0.0 |
| duration | number | 500 | 否 | 滑動(dòng)動(dòng)畫時(shí)長 | 1.0.0 |
| circular | boolean | false | 否 | 是否采用銜接滑動(dòng) | 1.0.0 |
| vertical | boolean | false | 否 | 滑動(dòng)方向是否為縱向 | 1.0.0 |
| display-multiple-items | number | 1 | 否 | 同時(shí)顯示的滑塊數(shù)量 | 1.9.0 |
| previous-margin | string | "0px" | 否 | 前邊距，可用于露出前一項(xiàng)的一小部分，接受 px 和 rpx 值 | 1.9.0 |
| next-margin | string | "0px" | 否 | 后邊距，可用于露出后一項(xiàng)的一小部分，接受 px 和 rpx 值。skyline 于 3.5.1 版本支持 | 1.9.0 |
| easing-function | string | "default" | 否 | 指定 swiper 切換緩動(dòng)動(dòng)畫類型 | 2.6.5 |
| | 合法值 | 說明 |
|---|
| default | 默認(rèn)緩動(dòng)函數(shù) | | linear | 線性動(dòng)畫 | | easeInCubic | 緩入動(dòng)畫 | | easeOutCubic | 緩出動(dòng)畫 | | easeInOutCubic | 緩入緩出動(dòng)畫 |
|
| direction | string | "all" | 否 | 指定 swiper 滑動(dòng)方向 | 3.8.10 |
| | 合法值 | 說明 |
|---|
| all | 默認(rèn) | | positive | 如 vertical 為 true 時(shí)，允許用戶下滑（swiper 內(nèi)容向上滾動(dòng)），為 false 時(shí)，允許用戶右滑（swiper 內(nèi)容向左滾動(dòng)） | | negative | 如 vertical 為 true 時(shí)，允許用戶上滑（swiper 內(nèi)容向下滾動(dòng)），為 false 時(shí)，允許用戶左滑（swiper 內(nèi)容向右滾動(dòng)） |
|
| bindchange | eventhandle | | 否 | current 改變時(shí)會(huì)觸發(fā) change 事件，event.detail = {current, source} | 1.0.0 |
| bindtransition | eventhandle | | 否 | swiper-item 的位置發(fā)生改變時(shí)會(huì)觸發(fā) transition 事件，event.detail = {dx: dx, dy: dy}。Skyline 僅支持非 worklet 的組件方法作為回調(diào)。 | 2.4.3 |
| bindanimationfinish | eventhandle | | 否 | 動(dòng)畫結(jié)束時(shí)會(huì)觸發(fā) animationfinish 事件，event.detail 同 bindchange。Skyline 僅支持非 worklet 的組件方法作為回調(diào)。 | 1.9.0 |
Skyline 特有屬性
| 屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 | 最低版本 |
|---|
| layout-type | string | normal | 否 | 渲染模式 | 3.2.0 |
| | 合法值 | 說明 |
|---|
| normal | 默認(rèn)方式 | | stackLeft | 左向堆疊 | | stackRight | 右向堆疊 | | tinder | 滑動(dòng)卡片 | | transformer | 過渡動(dòng)畫 |
|
| transformer-type | string | scaleAndFade | 否 | layout-type 為 transformer 時(shí)指定動(dòng)畫類型 | 3.2.0 |
| | 合法值 | 說明 |
|---|
| scaleAndFade | | | accordion | | | threeD | | | zoomIn | | | zoomOut | | | deepthPage | |
|
| indicator-type | string | normal | 否 | 指示點(diǎn)動(dòng)畫類型 | 3.2.0 |
| | 合法值 | 說明 |
|---|
| normal | | | worm | | | wormThin | | | wormUnderground | | | wormThinUnderground | | | expand | | | jump | | | jumpWithOffset | | | scroll | | | scrollFixedCenter | | | slide | | | slideUnderground | | | scale | | | swap | | | swapYRotation | | | color | |
|
| indicator-margin | number | 10 | 否 | 指示點(diǎn)四周邊距 | 3.2.0 |
| indicator-spacing | number | 4 | 否 | 指示點(diǎn)間距 | 3.2.0 |
| indicator-radius | number | 4 | 否 | 指示點(diǎn)圓角大小 | 3.2.0 |
| indicator-width | number | 8 | 否 | 指示點(diǎn)寬度 | 3.2.0 |
| indicator-height | number | 8 | 否 | 指示點(diǎn)高度 | 3.2.0 |
| indicator-alignment | Array.<number>/string | auto | 否 | 指示點(diǎn)的相對(duì)位置 | 3.2.0 |
| indicator-offset | Array.<number> | [0, 0] | 否 | 指示點(diǎn)位置的偏移量 | 3.2.0 |
| scroll-with-animation | boolean | true | 否 | 改變 current 時(shí)使用動(dòng)畫過渡 | 2.29.0 |
| cache-extent | number | 0 | 否 | 緩存區(qū)域大小，值為 1 表示提前渲染上下各一屏區(qū)域（swiper 容器大?。?/td> | 2.29.0 |
| worklet:onscrollstart | worklet | | 否 | 滑動(dòng)開始時(shí)觸發(fā)，僅支持 worklet 作為回調(diào)。event.detail = {dx: dx, dy: dy} | |
| worklet:onscrollupdate | worklet | | 否 | 滑動(dòng)位置更新時(shí)觸發(fā)，僅支持 worklet 作為回調(diào)。event.detail = {dx: dx, dy: dy} | |
| worklet:onscrollend | worklet | | 否 | 滑動(dòng)結(jié)束時(shí)觸發(fā)，僅支持 worklet 作為回調(diào)。event.detail = {dx: dx, dy: dy} | |
WebView 特有屬性
| 屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 | 最低版本 |
|---|
| snap-to-edge | boolean | false | 否 | 當(dāng) swiper-item 的個(gè)數(shù)大于等于 2，關(guān)閉 circular 并且開啟 previous-margin 或 next-margin 的時(shí)候，可以指定這個(gè)邊距是否應(yīng)用到第一個(gè)、最后一個(gè)元素 | 2.12.1 |
注意事項(xiàng)
layout-type 為 stackLeft stackRight 和 tinder 時(shí)僅支持 indicator-type=normalindicator-type 為 scrollFixedCenter swap swapYRotation 無法在循環(huán)模式 circular 下使用indicator-alignment 可指定為關(guān)鍵詞 auto 或 長度為 2 的數(shù)組。
- 橫向滑動(dòng)時(shí) auto 相當(dāng)于 bottomCenter [0, 1]
- 縱向滑動(dòng)時(shí)，auto 相當(dāng)于 centerRight [1, 0]
- 傳入數(shù)組時(shí)，表示 x/y 軸的相對(duì)位置，取值范圍 [-1, 1]，底邊中點(diǎn)為 [0, 1]
indicator-offset 是長度為 2 的數(shù)組，表示指示點(diǎn)在 x/y 軸上的偏移量，單位 px。- skyline 的
previous-margin、 display-multiple-items 和 vertical 屬性與 webview 表現(xiàn)略有不同，當(dāng)skyline 使用 next-margin 屬性且其值大于 0 時(shí)，會(huì)將前述三個(gè)屬性對(duì)齊 webview 實(shí)現(xiàn)。
渲染模式效果演示
指示器效果演示
Swiper 增強(qiáng)特性示例代碼
在開發(fā)者工具中預(yù)覽效果
change事件 source 返回值
從 1.4.0 開始，change事件增加 source字段，表示導(dǎo)致變更的原因，可能值如下：
autoplay 自動(dòng)播放導(dǎo)致swiper變化；touch 用戶劃動(dòng)引起swiper變化；- 其它原因?qū)⒂每兆址硎尽?/li>
Bug & Tip
tip: 如果在 bindchange 的事件回調(diào)函數(shù)中使用 setData 改變 current 值，則有可能導(dǎo)致 setData 被不停地調(diào)用，因而通常情況下請(qǐng)?jiān)诟淖?current 值前檢測 source 字段來判斷是否是由于用戶觸摸引起。tip: 在 mac 小程序上，若當(dāng)前組件所在的頁面或全局開啟了 enablePassiveEvent 配置項(xiàng)，該內(nèi)置組件可能會(huì)出現(xiàn)非預(yù)期表現(xiàn)（詳情參考 enablePassiveEvent 文檔）
示例代碼
在開發(fā)者工具中預(yù)覽效果
