更新记录
2.1.0(2026-10-31) 下载此版本
- 改为 uni_modules 规范结构(
uni_modules/czh-swiper),支持插件市场一键导入、从市场更新与代码对比 - 补充
package.json,声明插件分类与平台兼容性(uni-app x:App 三端支持) - 组件实现、Props、Events、Methods 与 2.0.0 完全一致,无破坏性变更;插槽用法不变,无需修改业务代码
2.0.0(2025-08-15) 下载此版本
修复原有的bug
1.0.0(2023-04-24) 下载此版本
插件首次发布
查看更多平台兼容性
uni-app x(4.71)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
czh-swiper 三槽位循环滑动组件(uni-app x)
左右滑动切换数据的容器组件,适用于答题、阅读等超长列表 + 单条内容很重(富文本、大量子节点)的场景。 组件为 uni-app x(uvue + UTS + Vue3 组合式 API)实现,easycom 直接使用,无需注册。
本示例工程 pages/index/index.uvue 演示了组件的完整使用场景:题号状态栏、长内容滚动、上一题/下一题、定位跳转、试用边界、自动切题、列表筛选与重新加载。
安装
组件已按 uni_modules 规范发布,二选一:
- 插件市场:插件详情页点「使用 HBuilderX 导入插件」,选择目标项目,导入后自动落在
uni_modules/czh-swiper; - 手动:把
uni_modules/czh-swiper整个目录复制到项目根目录的uni_modules下。
uni_modules/czh-swiper/
├─ package.json
├─ readme.md
├─ changelog.md
└─ components/czh-swiper/czh-swiper.uvue
组件位于 uni_modules/*/components/组件名/组件名.uvue,符合 easycom 自动扫描规则:页面里直接写 <czh-swiper>,不需要 import,也不需要注册。
仅支持 uni-app x(uvue),不支持 uni-app(vue2/vue3)。
设计理念
旧版(5 swiper,已废弃)
- 初始化 5 个 swiper-item,当前题(第 n 条)前后各预填 2 条数据;
- 向右滑时动态更新 n+2 槽位、向左滑更新 n-2 槽位(隔一个更新);
- 预填的目的是:快速滑动时相邻槽位的数据已经就绪,过渡平滑;
- 代价:永远维护 5 份内容,且槽位下标与数据下标的换算逻辑复杂(
% 5、slice重排、分组重置……),旧版的一系列 bug 都出在这里。
新版(3 swiper,本组件)
- 无论数据多少条,固定 3 个槽位循环(circular)复用,数据不足 3 条时为实际条数;
- 任一时刻只渲染当前槽位,相邻槽位是占位内容,滑动结束后才渲染真实内容——列表再长也只维护一份重内容,内存与渲染开销和列表长度无关;
- 没有邻居数据需要同步,槽位只是匿名容器,下标换算只剩
(newTab - oldTab + 3) % 3一个方向判断,从根上消灭了旧版 bug 来源; - 滑动过程中的占位由
duration=0(默认)的瞬时切换兜底,不会看到长时间空白。
关键机制(生产环境验证)
- 两步销毁:切换槽位时先让新旧槽位同帧渲染,
nextTick后再移除旧槽位,避免富文本等重组件的销毁与创建落在同一个渲染任务里(部分平台会异常); - change 回调延后一帧修改
current,避免在 change 事件回调里同步改 current 触发二次动画; - 边界回弹用销毁重建实现(循环模式下 change 已经发生,重建后停留在原槽位)。
API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| count | number | 0 | 数据总条数(列表长度) |
| index | number | 0 | 当前数据下标,支持 v-model:index |
| height | number | 0 | swiper 高度(px),0 表示撑满父容器 |
| limit-index | number | -1 | 试用边界:允许展示的最大数据下标,-1 不限制 |
| disable-touch | boolean | false | 是否禁用手势滑动(自动切题倒计时等场景;next/prev 程序切换不受影响) |
| duration | number | 0 | 滑动动画时长(ms),0 立即切换 |
Events
| 事件 | 参数 | 说明 |
|---|---|---|
| update:index | index: number | v-model:index 同步当前下标 |
| change | index: number | 当前数据下标变化(手势滑动 / next / prev / position)。页面在此重置滚动位置、清空并重新拉取当前条的关联数据 |
| overflow | direction: string | 越界('next' 末尾向前 / 'prev' 首部向后),页面自行 toast / 振动 |
| limit | - | 触达试用边界(对应试用题库的激活引导弹窗) |
Slots
| 插槽 | 说明 |
|---|---|
| default | 当前条内容。从页面自身状态取当前条数据(如 somedata[nowIndex]),直接修改数组元素字段即可刷新显示 |
| placeholder | 相邻槽位的占位内容,仅在滑动过程中短暂可见 |
Methods(通过 ref 调用)
| 方法 | 说明 |
|---|---|
| position(index) | 定位到某条数据(答题卡跳转):内容直接切换,不滑动、不重建 swiper |
| next() | 下一条:内容原地替换,不产生滑动动画;越界触发 overflow、试用边界触发 limit |
| prev() | 上一条:行为同 next |
// easycom 组件 ref 类型:标签名首字母大写驼峰 + ComponentPublicInstance
const swiperRef = ref<CzhSwiperComponentPublicInstance | null>(null)
swiperRef.value?.next?.()
swiperRef.value?.position?.(13)
基本用法
<czh-swiper v-model:index="nowIndex" :count="somedata.length" :height="scrollHeight"
:limit-index="limitIndex" :disable-touch="autoSwitching"
@change="onQuestionChange" @overflow="onOverflow" @limit="onLimit">
<!-- 当前条内容:数据在页面侧,组件不感知业务,无泛型/any 类型问题 -->
<scroll-view direction="vertical" :scroll-top="scrollTop" :style="{ height: scrollHeight + 'px' }">
<!-- somedata[nowIndex] 的内容,直接改字段即可刷新 -->
</scroll-view>
<!-- 相邻槽位占位 -->
<template #placeholder>
<view><text>加载中...</text></view>
</template>
</czh-swiper>
列表加载 / 筛选 / 刷新
// 首次加载并定位到指定进度
nowIndex.value = learnId
somedata.value = list // count 变化,组件自动初始化并定位
// 筛选 / 整体刷新:count 与 index 一起写,组件按新条数重建并回到指定下标
nowIndex.value = 0
somedata.value = filteredList
// 只改某条数据的内容:直接改数组元素字段即可,插槽内容通过引用共享自动更新
somedata.value[nowIndex.value].myAnswer = 2
边界与试用
// 越界提示(组件已自动回弹到原位)
const onOverflow = (direction: string) => {
uni.showToast({ title: direction == 'next' ? '已经到最后一题了~' : '已经到第一题了~', icon: 'none' })
}
// 试用边界:展示前 5 题(limitIndex = 4),到边界继续向前滑不切题,弹激活引导
const onLimit = () => { /* 打开激活弹窗 */ }
自动切题(禁手势)
const autoSwitching = ref(false)
// :disable-touch="autoSwitching" 绑定到组件
// 倒计时结束先解除标记再调用 next(),next/prev 不受 disable-touch 影响
横竖屏 / 窗口宽度变化
在页面 onResize 里更新一个宽度值并作为组件的 :key,宽度变化时重建组件(重挂载后自动按 index 恢复位置),避免内容按旧宽度排版:
<czh-swiper :key="winWidth" ...>
onResize(() => {
winWidth.value = uni.getWindowInfo().windowWidth
scrollHeight.value = /* 重新计算 */
})
注意事项
count变化时请同步更新index(如重置到 0),两个 prop 会一起生效;duration保持 0(默认):相邻槽位是占位内容,动画时长越长占位可见时间越久;- 「上一题/下一题」按钮的行为是内容原地替换(无滑动动画),与手势滑动是两条路径,均为生产验证过的行为;
- 键盘遮挡输入框、回到顶部按钮等滚动细节属于页面职责(内容插槽在页面侧),由页面自行处理(如键盘弹起时调整滚动位置、切题后回到顶部)。

收藏人数:
下载插件并导入HBuilder
下载示例项目ZIP
赞赏(0)
下载 154
赞赏 0
下载 12777956
赞赏 1960
赞赏
京公网安备:11010802035340号