救命这个 React 组件库我装了就不想卸载CarouselModal 居然还能这样玩看完直接扔掉 Swiper你还在为轮播图和弹窗写几百行样板代码吗兄弟们听我说每次写 React 项目轮播图要上swiper弹窗要上react-modal两个库加起来 bundle 直奔 200KB配置起来恨不得写篇论文。然后你还要处理自动播放、悬停暂停、循环轮播、无限克隆弹窗的滚动锁、ESC 关闭、遮罩层穿透多个弹窗同时存在时的 z-index 管理销毁时内存泄漏等等咱就是说有没有一个库一个包全解决才 160KB unpacked压缩后更小零配置开箱即用API 优雅得像苹果的设计有。它就是——snapzy-js。一、snapzy-js 到底是什么神仙库简单粗暴一个用 Vite TypeScript React 19 写的 Carousel轮播图 Modal弹窗双功能组件库。包名snapzy-jsnpm 下载MIT 协议作者 Ha Tranv1.0.13代码干净得像刚擦过的 MacBook 屏幕。 核心亮点功能一句话总结Carousel支持多图同屏、无限循环、自动播放、自定义按钮、分页器圆点Modal支持多弹窗、ESC/遮罩/按钮三态关闭、滚动锁、自定义 Footer体积打包后 ~46KBunpacked 160KB构建双格式输出ESM UMDReact 19 Ready方案风格所有样式封装在 CSS 模块中可选导入二、Carousel强到离谱的轮播组件2.1 一分钟上手import { Carousel, Slide } from snapzy-js; import snapzy-js/style.css; function App() { return ( Carousel Slide 幻灯片 1/Slide Slide 幻灯片 2/Slide Slide 幻灯片 3/Slide /Carousel ); }就这就这3 个 Slide 子组件往 Carousel 里一扔轮播图就跑起来了。2.2 功能全开版本Carousel items{3} // 一次显示 3 张 controls{true} // 显示左右箭头 nav{true} // 显示底部导航圆点 loop{true} // 无限循环 autoplay{true} // 自动播放 autoplayInterval{2000} // 2 秒切换 autoplayHoverPause{true} // 鼠标悬停暂停 speed{500} // 500ms 过渡动画 slideBypage // 每次翻一整页 prevButton{MyPrevIcon /} // 自定义上一页按钮 nextButton{MyNextIcon /} // 自定义下一页按钮 {slides} /Carousel2.3 我扒了源码发现了几个骚操作 无限循环克隆魔法你以为loop{true}就是简单的 “到最后一张回到第一张”不snapzy-js 用了 “克隆” 方案——在首尾各插入克隆 slide然后利用 CSS transition 做无缝衔接// 伪代码双向克隆if(loop){constheadClonesslides.slice(-cloneCount)// 在头部插入尾部克隆consttailClonesslides.slice(0,cloneCount)// 在尾部插入头部克隆allSlides[...headClones,...originalSlides,...tailClones]}当用户滚动到尾部克隆时趁过渡动画结束的瞬间用transition: none把位置瞬移到对应的原始 slide 上。用户根本察觉不到consttransition(instantfalse){track.style.transitioninstant?none:transform${speed}mstrack.style.transformtranslateX(${-(currentIndex*(100/items))}%)}这就是 “丝滑如德芙” 背后的代码。⏱ 自动播放的清理机制useEffect((){if(!autoplay)returnconsttimersetInterval(()moveSlide(slideBy),interval)return()clearInterval(timer)// 组件卸载必清理不内存泄漏},[autoplay,interval,slideBy,moveSlide])这个return () clearInterval是 React 标准模式但很多开源库会漏掉。snapzy-js干干净净。 悬停暂停useEffect((){constelcontainerRef.currentif(!el)returnif(autoplayhoverPause){el.addEventListener(mouseenter,stopAutoPlay)el.addEventListener(mouseleave,startAutoPlay)return(){el.removeEventListener(mouseenter,stopAutoPlay)el.removeEventListener(mouseleave,startAutoPlay)}}},[hoverPause,autoplay,startAutoPlay,stopAutoPlay])事件监听也做了清理完美无泄漏。三、Modal你的弹窗不需要 z-inde 焦虑3.1 一行都不用写弹窗状态import { Modal, Open, Content, Footer } from snapzy-js; function App() { return ( Modal Open namedemo button 点我打开弹窗/button /Open Content openNamedemo div h2哇哦弹窗出现了/h2 p看到没我连 useState 都没写。/p /div /Content Footer button确认/button button取消/button /Footer /Modal ); }你没看错0 行状态管理代码。Open和Content通过name/openName关联Modal容器通过 Context API 做状态协调。3.2 它的骚操作三态关闭typeCloseMethodbutton|overlay|escape// 默认全开closeMethods{[button,overlay,escape]}方式说明button弹窗右上角 X 按钮overlay点击遮罩层关闭可禁用强制用户操作escape键盘 ESC 键关闭3.3 多重弹窗居然不打架我用 Context API 全局堆栈window.__modalStack实现多弹窗管理// 全局弹窗堆栈确保 ESC 只关最上层modalOpen(name){__modalStack.push(name)}modalClose(){__modalStack.pop()// 只有栈顶弹窗响应 ESCif(topModalNamenamehandleEscape){document.addEventListener(keydown,onEscape)}}同时有 3 个弹窗叠叠乐按 ESC 只会关掉最上面那个。3.4 滚动锁人体工学细节有没有遇到过打开弹窗后背景还能滚动的尴尬if(hasScrollbar(target)isFirstModal){constoriginalPaddinggetComputedStyle(target).paddingRightconstscrollbarWidthwindow.innerWidth-document.documentElement.clientWidth target.style.overflowhiddentarget.style.paddingRightoriginalPaddingscrollbarWidthpx}先算滚动条宽度再锁。这样锁滚动时页面不会跳一下因为滚动条消失后padding 自动顶上。四、代码质量看一眼就想 Star4.1 构建系统Vite 6 TypeScript 5.7package.json ├── main: dist/index.js # CJS ├── module: dist/index.es.js # ESM ├── types: dist/index.d.ts # TypeScript 类型 ├── style: dist/style.css # 可选样式双格式输出既支持script直引也支持import。4.2 依赖极其精简dependencies: clsx # 条件 className2.3KB react ^19 # 你本来就有 react-dom ^19 # 你本来就有 sass # SCSS 编译唯一非标准依赖只有clsx2.3KB 的小工具。这意味着 snapzy-js几乎不增加你的 bundle 体积。4.3 CSS Module 方案代码摘录._wrapper_1nnxy_1 { position: relative; } ._track_1nnxy_9 { display: flex; align-items: center; } ._slide_1nnxy_14 { flex: 0 0 auto; } ._prev_1nnxy_18, ._next_1nnxy_19 { position: absolute; width: 32px; height: 32px; background-color: #ccc; opacity: .7; border-radius: 50%; } ._dot_1nnxy_52 { width: 12px; height: 12px; background-color: #ccc; border-radius: 50%; } ._dot_1nnxy_52._active_1nnxy_58 { background-color: #333; } ._overlay_1aq0n_1 { position: fixed; inset: 0; background-color: #191b1d73; z-index: 99; opacity: 0; visibility: hidden; transition: opacity .2s, visibility .2s; } ._overlay_1aq0n_1._show_1aq0n_14 { opacity: 1; visibility: visible; } ._content_1aq0n_19 { padding: 30px; background-color: #fff; border-radius: 16px; box-shadow: 0 7px 29px #64646f33; }用哈希类名_1nnxy_避免样式冲突默认颜色中性耐看开箱即用。五、和其他库的对比硬核数据说话对比项snapzy-jsswiper/reactreact-modal轮播弹窗一体✅❌❌TypeScript✅✅✅React 19✅⚠️⚠️ESM CJS✅✅✅无限循环✅✅N/A多图同屏✅✅N/A自动播放 悬停暂停✅✅N/A自定义按钮✅✅N/AESC/遮罩/按钮关闭✅N/A❌需自己写滚动锁✅N/A❌需插件多弹窗栈管理✅N/A❌包体积压缩后~46KB~120KB~75KB依赖数6几乎都你已有1510六、结语适合什么场景✅ 快速搭建官网轮播 弹窗✅ 个人项目不想被 swiper 巨兽支配✅ 需要 React 19 原生支持的组件✅ 喜欢干净、简单、无胶水代码的人✅ 对包体积敏感的电商/落地页❌ 需要复杂手势捏合、旋转的图片画廊一句话如果 Swiper 的配置项看得你眼花snapzy-js 就是你的甜点。npm install snapzy-js GitHub MIT License下一篇预告什么看完 snapzy-js 还不过瘾下一篇我将手撕另一个 React 神库——它的源码只有 200 行却让无数人直呼我这几年代码白写了关注、收藏、不迷路 正在更新《React 开源库源码分析》系列欢迎点赞、收藏、转发