更新记录

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(默认):相邻槽位是占位内容,动画时长越长占位可见时间越久;
  • 「上一题/下一题」按钮的行为是内容原地替换(无滑动动画),与手势滑动是两条路径,均为生产验证过的行为;
  • 键盘遮挡输入框、回到顶部按钮等滚动细节属于页面职责(内容插槽在页面侧),由页面自行处理(如键盘弹起时调整滚动位置、切题后回到顶部)。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议