如何为BoxSlider编写自定义滑动效果:从Effect接口到createProgressiveTransition实战
如何为BoxSlider编写自定义滑动效果:从Effect接口到createProgressiveTransition实战
BoxSlider(@boxslider/slider)是一个零依赖的轻量级内容轮播库,内置 Carousel、Fade、Cube、Tile 四种效果。想做出官网没有的过渡动画?本文带你从 Effect 接口讲起,用 createProgressiveTransition 实战写一个支持拖拽跟手的自定义滑动效果。
为什么需要自定义滑动效果
内置效果覆盖了常见场景,但一旦你的设计稿要求"缩放淡入"、"翻转入场"、"碎片拼合"这类个性化动画,就需要自己实现效果。
BoxSlider 的设计思路是:滑动的骨架(自动播放、循环、触摸手势、无障碍属性)由核心库负责,动画本身交给一个可插拔的效果对象。你只需要关注"两张幻灯片之间怎么变",其余全部托管。
下面这张图就是轮播中的一张普通幻灯片——它可以是图片、视频、任意 HTML 内容:
认识 Effect 接口:自定义效果的入口
完整定义见 types.ts,一个效果对象只需实现三个方法(外加一个可选属性):
| 成员 | 必填 | 作用 |
|---|---|---|
initialize(el, slides, options, stateStore) |
✅ | 给所有幻灯片设置初始状态(定位、透明度等) |
prepareTransition(settings) |
✅ | 每次切换前被调用,返回一个"过渡控制器" |
destroy(el, slides) |
❌ | 滑块销毁时清理动画、定时器、监听器 |
swipeDirection |
❌ | 声明手势方向,设为 'vertical' 则响应上下滑动 |
其中 prepareTransition 收到的 TransitionSettings 包含 slides、currentIndex、nextIndex、speed、isPrevious 等信息,是编写动画的全部原料。
用 createProgressiveTransition 构建渐进式过渡
这是本库最贴心的辅助函数,源码在 utils.ts。它把"用户边拖边跟手"的复杂逻辑封装好了,你只需要传入回调:
| 回调 | 触发时机 | 你该做什么 |
|---|---|---|
onProgress(progress) |
拖拽过程中(0~1) | 直接用 CSS 更新视觉状态 |
onComplete(fromProgress, remainingDuration) |
拖拽超过阈值,动画播放完成 | 用 Web Animations API 补完剩余动画 |
onCancel(fromProgress, remainingDuration) |
拖拽不足,弹回原位 | 反向动画回起点 |
onFinish() |
过渡完成 | 写最终样式(动画会自动清理,无需手动 cancel) |
onReset() |
取消/中断 | 恢复初始样式 |
所有回调都是可选的。想要最简单的"硬切"效果,只写 onFinish 即可。
实战:编写一个缩放淡入效果
完整示例可参考 Fade 效果实现,下面是一个带缩放感的精简版,共三步:
第一步:initialize 让幻灯片重叠定位
initialize(el, slides, options) {
el.style.setProperty('position', 'relative')
slides.forEach((slide, index) => {
slide.style.setProperty('position', 'absolute')
slide.style.setProperty('inset', '0')
slide.style.setProperty('opacity',
index === options.startIndex ? '1' : '0')
})
}
第二步:onProgress 让动画"跟手"
onProgress: (progress) => {
currentSlide.style.opacity = String(1 - progress)
nextSlide.style.opacity = String(progress)
nextSlide.style.transform = `scale(${0.9 + progress * 0.1})`
}
第三步:onComplete 补完剩余动画
onComplete: async (fromProgress, remainingDuration) => {
await nextSlide.animate(
{ opacity: [String(fromProgress), '1'] },
{ duration: remainingDuration, fill: 'forwards' },
).finished
}
⚠️ 两个容易踩的坑:
- 动画前记得先
cancelAnimations(currentSlide, nextSlide),避免上一次动画残留; remainingDuration已由框架算好(=speed× 剩余比例),不要自己乘以完整 speed,否则会拖长动画。
拖拽跟手是 BoxSlider 体验的精髓:手指滑动多少,画面就跟进多少,松手时按进度(>50%)或速度决定完成还是弹回。这套判定逻辑在 BoxSlider 核心类 中已经帮你实现,效果侧只管渲染即可。
注册自定义效果并运行
把效果对象作为第二个参数传给 BoxSlider 即可,选项(speed、timeout、loop 等)见 configuration 文档:
import { BoxSlider } from '@boxslider/slider'
const slider = new BoxSlider(document.getElementById('slider'), myEffect, {
speed: 300,
})
如果想做成 Web Component 复用,只需继承 Slider 并在 connectedCallback 中调用 this.init(effect),然后 customElements.define('my-slider', CustomSlider)——官方文档 09-custom-effect.md 提供了完整模板,仓库中还有可直接对照的 CustomEffect 示例。
最佳实践清单
- ✅ 效果尽量只操作 CSS 属性(
opacity、transform),性能最好 - ✅ 需要保留原始样式时用
initialize里的stateStore暂存,销毁时自动还原 - ✅ 复杂动画参考 Tile 效果实现:它把网格拆分与逐块过渡拆成了独立模块
- ⚠️ 考虑浏览器兼容、无障碍与性能,示例代码仅供演示
- ⚠️
prepareTransition可以返回null表示"本次不切换"(例如边界禁用时)
从零实现一个自定义滑动效果,核心就一句话:initialize 摆好阵型,prepareTransition 交给 createProgressiveTransition,剩下的交给 BoxSlider。



