在 refine 项目中使用 Swiper.js构建触摸滑动轮播与缩略图画廊的完整指南【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineSwiper.js 是一款轻量而强大的 JavaScript 触摸滑动库可用于为网站与 Web 应用快速添加支持触摸手势、响应式布局的轮播Slider组件。本文将以当前 refine 仓库中 documentation/blog/2023-12-07-swiper-js.md 为骨架结合仓库内 examples/win95/src/routes/rvc-website/home.tsx 的真实使用案例系统讲解 Swiper 的安装、初始化、模块自定义、React 集成以及 Web Component 用法帮助你掌握从零搭建可定制轮播的完整技术方案。Swiper.js 是什么为什么轮播场景值得选择它滑块Slider已经成为网站与 Web 应用不可或缺的组成部分它能够快速抓住用户的注意力并突出展示重要的信息、商品或特性。市面上有大量用于制作滑块的库而Swiper是其中值得关注的一个。Swiper.js是一个强大的 JavaScript 库可以让你快速为网站或 Web 应用添加支持触摸和响应式布局的滑块。它之所以被广泛采用主要得益于两点定制灵活度高支持模块化架构按需加载 Navigation导航、Pagination分页、Scrollbar滚动条、Thumbs缩略图等能力框架支持广泛除原生 JavaScript 外还提供了 React、Vue、Angular 等主流框架的官方绑定。在 refine 仓库中Swiper 也确实被真实用于构建前端展示场景win95 示例项目的首页使用swiper/react渲染最新上映影片横滑列表详见下文仓库实战小节这为本文的实践部分提供了可直接对照的仓库级范例。在项目中引入 Swiper.js 的三种方式1. 下载 Swiper 资源如果你希望完全离线使用可以下载 Swiper 的本地资源包完整压缩包可通过其发布渠道获取然后将 CSS 与 JS 文件放入项目静态目录手动引入。2. 通过 CDN 引入只需在 HTML 文件中添加以下代码即可通过 CDN 快速引入 Swiper 的样式与脚本link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/swiper11/swiper-bundle.min.css / script srchttps://cdn.jsdelivr.net/npm/swiper11/swiper-bundle.min.js/script如果你在浏览器中直接使用 ES Modules也有对应的 CDN 版本script typemodule import Swiper from https://cdn.jsdelivr.net/npm/swiper11/swiper-bundle.min.mjs const swiper new Swiper(...) /script注意上面的版本号为11这与当前仓库中锁定安装的 Swiper 大版本一致详见下文版本事实。3. 通过 npm 安装对于 React 等模块化项目推荐使用 npm或 pnpm/yarn安装npm install swiper然后在你自己的 JavaScript / TypeScript 文件中导入// import Swiper JS import Swiper from swiper; // import Swiper styles import swiper/swiper-bundle.min.css; const swiper new Swiper(...);核心与模块的区别Swiper 默认只导出基础版本不包含任何附加模块如Navigation、Pagination等。因此你需要从swiper/modules中额外导入并配置这些模块// core version navigation, pagination modules: import Swiper from swiper; import { Navigation, Pagination } from swiper/modules; // import Swiper and modules styles import swiper/swiper.min.css; import swiper/modules/navigation.min.css; import swiper/modules/pagination.min.css; // init Swiper: const swiper new Swiper(.swiper, { // configure Swiper to use modules modules: [Navigation, Pagination], ... });如果你希望一次性导入包含全部模块的完整包bundle可以从swiper/bundle导入// import Swiper bundle with all modules installed import Swiper from swiper/bundle; // import styles bundle import swiper/swiper-bundle.min.css; // init Swiper: const swiper new Swiper(...);定义 Swiper 的 HTML 结构安装完成后需要为 Swiper 搭建标准的 HTML 布局。Swiper 对标记结构有明确约定外层为容器.swiper内部必须包含.swiper-wrapper与若干.swiper-slide其余分页、导航、滚动条均为可选挂载点!-- Slider main container -- div classswiper !-- Additional required wrapper -- div classswiper-wrapper !-- Slides -- div classswiper-slideSlide 1/div div classswiper-slideSlide 2/div div classswiper-slideSlide 3/div ... /div !-- If we need pagination -- div classswiper-pagination/div !-- If we need navigation buttons -- div classswiper-button-prev/div div classswiper-button-next/div !-- If we need scrollbar -- div classswiper-scrollbar/div /div初始化 Swiper两个核心参数在 HTML 就绪后通过new Swiper(...)完成初始化const swiper new Swiper(.swiper, { // Optional parameters direction: vertical, loop: true, // If we need pagination pagination: { el: .swiper-pagination, }, // Navigation arrows navigation: { nextEl: .swiper-button-next, prevEl: .swiper-button-prev, }, // And if we need scrollbar scrollbar: { el: .swiper-scrollbar, }, });Swiper构造函数接受两个参数目标元素以CSS选择器形式指向 Swiper 的容器元素上例中的.swiper配置对象用于传入navigation、pagination、modules、scrollbar、direction、loop等大量可选配置项。Swiper 的配置参数非常丰富官方 API 文档中列出了完整的参数清单在本文后续小节我们会结合仓库源码逐一剖析最常用的模块参数。Swiper 的常用方法与属性初始化之后就可以通过 Swiper 实例访问一系列实用的属性swiper.activeIndex当前滑块的索引值可赋值为数字swiper.previousIndex上一个滑块的索引值可赋值为数字swiper.allowSlideNext禁用或启用切换到下一张滑块的能力swiper.allowSlidePrev禁用或启用切换到上一张滑块的能力swiper.el滑块容器对应的 HTML 元素swiper.width滑块容器的宽度swiper.height滑块容器的高度swiper.swipeDirection指定滑动方向取值为prev或next。以及常用的方法swiper.changeDirection(direction, needUpdate)swiper.slidePrev(speed, runCallbacks)swiper.slideTo(index, speed, runCallbacks)在仓库的 win95 示例中正是通过controlledSwiper?.slidePrev()与controlledSwiper?.slideNext()驱动自定义箭头按钮切换轮播与本文介绍的方法用法完全一致。监听 Swiper 事件Swiper 内置了许多有用的事件可以通过两种方式绑定方式一初始化时通过on参数注册const swiper new Swiper(.swiper, { // ... on: { init: function () { console.log(swiper initialized); }, }, });方式二初始化后通过实例的on方法注册const swiper new Swiper(.swiper, { // ... }); swiper.on(slideChange, function () { console.log(slide changed); });常用事件包括activeIndexChange当滑块的当前索引发生变化时触发slideChange当滑块的活动索引发生变化时触发click当 Swiper 容器被点击时触发。在 React 集成中这些事件会以on{事件名}的 props 形式暴露见下文React 中的 Swiper props。Swiper 的样式体系Swiper 提供多套 CSS 样式集按需选择即可swiper/swiper-bundle.min.cssSwiper 核心样式与所有模块样式的合并压缩版swiper/swiper.min.css仅 Swiper 核心样式不含模块样式swiper/modules/{{moduleName}}.min.css按小写模块名如 Navigation、Pagination对应的压缩模块样式swiper/modules/{{moduleName}}.css同上但为未压缩版本。Swiper 也支持单独导入模块样式——例如只导入导航模块的压缩样式import swiper/modules/navigation.min.css;注意如果已经导入了 bundle 样式则模块样式是可选的无需重复导入。此外 Swiper 官方还提供 SCSS、Less 等其他样式方案。深入自定义 Swiper 模块Swiper 的模块可以通过参数进行多样化定制下面逐一讲解。Navigation 导航Navigation 模块提供两个核心参数prevEl字符串类型值为 CSS 选择器或 HTML 元素指向点击后切换上一张的按钮nextEl字符串类型值为 CSS 选择器或 HTML 元素指向点击后切换下一张的按钮。以下示例将 HTML 模板中的.swiper-button-prev、.swiper-button-next元素分别绑定到navigation.prevEl与navigation.nextElJavaScript 代码import Swiper from swiper; import { Navigation } from swiper/modules; // import Swiper and modules styles import swiper/swiper.min.css; import swiper/modules/navigation.min.css; const swiper new Swiper(.swiper, { modules: [Navigation], ...., // Navigation arrows navigation: { nextEl: .swiper-button-next, prevEl: .swiper-button-prev, }, }); // OR (Alternative) const swiper new Swiper(.swiper, { modules: [Navigation], ...., }); swiper.nextEl .swiper-button-next; swiper.prevEl .swiper-button-prev;HTML 模板!-- Slider main container -- div classswiper !-- Additional required wrapper -- div classswiper-wrapper !-- Slides -- div classswiper-slideSlide 1/div div classswiper-slideSlide 2/div div classswiper-slideSlide 3/div ... /div !-- navigation buttons -- div classswiper-button-prev/div div classswiper-button-next/div /divPagination 分页Pagination 模块提供以下参数bullets数组类型存放所有分页小圆点的 HTML 元素例如通过swiper.pagination.bullets[1]获取指定滑块的圆点元素el分页容器元素的 HTMLElement。以下示例将.swiper-pagination绑定到pagination.el并开启clickable点击圆点跳转对应滑块JavaScript 代码import Swiper from swiper; import { Pagination, Navigation } from swiper/modules; // import Swiper and modules styles import swiper/swiper.min.css; import swiper/modules/navigation.min.css; import swiper/modules/pagination.min.css; const swiper new Swiper(.swiper, { modules: [Pagination, Navigation], // If we need pagination pagination: { el: .swiper-pagination, clickable: true }, ... }); // OR (Alternative) const swiper new Swiper(.swiper, { modules: [Pagination, Navigation], ..., }); swiper.el .swiper-pagination;HTML 模板!-- Slider main container -- div classswiper !-- Additional required wrapper -- div classswiper-wrapper !-- Slides -- div classswiper-slideSlide 1/div div classswiper-slideSlide 2/div div classswiper-slideSlide 3/div ... /div !-- If we need pagination -- div classswiper-pagination/div /divScrollbar 滚动条Scrollbar 模块提供以下参数dragEl滚动条中可拖拽手柄元素的 HTMLElementel滚动条容器元素的 HTMLElement。以下示例将.swiper-scrollbar绑定到scrollbar.elJavaScript 代码import Swiper from swiper; import { Scrollbar } from swiper/modules; // import Swiper and modules styles import swiper/swiper.min.css; import swiper/modules/scrollbar.min.css; const swiper new Swiper(.swiper, { modules: [Scrollbar], // And if we need scrollbar scrollbar: { el: .swiper-scrollbar, }, }); // OR (Alternative) const swiper new Swiper(.swiper, { modules: [Scrollbar], ...., }); swiper.el .swiper-scrollbar;HTML 模板!-- Slider main container -- div classswiper !-- Additional required wrapper -- div classswiper-wrapper !-- Slides -- div classswiper-slideSlide 1/div div classswiper-slideSlide 2/div div classswiper-slideSlide 3/div ... /div !-- If we need scrollbar -- div classswiper-scrollbar/div /divThumbs 缩略图实现缩略图画廊需要两个 Swiper 实例协同工作第一个 Swiper 实例主滑块由缩略图控制其切换第二个 Swiper 实例缩略图滑块本身。Thumbs 模块的核心参数swiper接收缩略图 Swiper 的实例。以下示例通过swiper2主滑块的thumbs.swiper属性引用swiper缩略图滑块实例JavaScript 代码import Swiper from swiper; import { Thumbs } from swiper/modules; // import Swiper and modules styles import swiper/swiper.min.css; import swiper/modules/thumbs.min.css; // Initialize Swiper let swiper new Swiper(.mySwiper, { spaceBetween: 10, slidesPerView: 4, freeMode: true, watchSlidesProgress: true, }); let swiper2 new Swiper(.mySwiper2, { modules: [Thumbs], spaceBetween: 10, thumbs: { swiper: swiper, }, });这里缩略图滑块开启freeMode与watchSlidesProgress前者让缩略图可以自由滑动、后者确保缩略图的进度高亮能随主滑块实时同步——这是画廊类轮播的常见组合。HTML 模板div classswiper-container div classswiper mySwiper2 div classswiper-wrapper div classswiper-slide slide_1Slide 1/div div classswiper-slide slide_2Slide 2/div div classswiper-slide slide_3Slide 3/div div classswiper-slide slide_4Slide 4/div div classswiper-slide slide_5Slide 5/div /div div classswiper-button-next/div div classswiper-button-prev/div /div div thumbsSlider classswiper mySwiper div classswiper-wrapper div classswiper-slide slide_1Slide 1/div div classswiper-slide slide_2Slide 2/div div classswiper-slide slide_3Slide 3/div div classswiper-slide slide_4Slide 4/div div classswiper-slide slide_5Slide 5/div /div /div /div在 React 中使用 SwiperSwiper 支持 React、Vue、Angular 等主流框架本节聚焦 React 集成方式。安装与组件导入Swiper React 属于主 Swiper 库的一部分仅通过 NPM 访问npm i swiper安装完成后从swiper/react导出即可使用 React 组件。基础用法Swiper与SwiperSlideswiper/react导出两个核心组件Swiper/Swiper代表 Swiper 容器元素SwiperSlide/SwiperSlide代表单个滑块。// Import Swiper React components import { Swiper, SwiperSlide } from swiper/react; // Import Swiper styles import swiper/css; export default () { return ( Swiper SwiperSlideContent 1/SwiperSlide SwiperSlideContent 2/SwiperSlide SwiperSlideContent 3/SwiperSlide SwiperSlideContent 4/SwiperSlide /Swiper ); };注意Swiper React 默认使用 Swiper 核心版不含附加模块。如果要使用Navigation、Pagination等模块必须先通过modules引入// import Swiper core and required modules import { Navigation, Pagination, Scrollbar, A11y } from swiper/modules; import { Swiper, SwiperSlide } from swiper/react; // Import Swiper styles import swiper/css; import swiper/css/navigation; import swiper/css/pagination; import swiper/css/scrollbar; export default () { return ( Swiper // install Swiper modules modules{[Navigation, Pagination, Scrollbar, A11y]} navigation{true} pagination{true} SwiperSlideContent 1/SwiperSlide SwiperSlideContent 2/SwiperSlide SwiperSlideContent 3/SwiperSlide SwiperSlideContent 4/SwiperSlide ... /Swiper ); };其中A11y是无障碍模块增强键盘与读屏器支持搭配navigation{true}、pagination{true}即可一键开启上一张/下一张按钮与分页圆点。Swiper props所有 Swiper 参数都会作为组件props传给Swiper此外还附加了以下属性tagSwiper 容器的 HTML 元素标签wrapperTagSwiper wrapper 的 HTML 元素标签onSwiper接收 Swiper 实例的回调。同时所有 Swiper 事件都以on{事件名}形式暴露为 props例如SlideChange事件对应onSlideChange... Swiper onSlideChange{() {/*...*/}} ... 在仓库的 win95 示例中onSwiper{(swiper) setControlledSwiper(swiper)}正是利用该回调把 Swiper 实例存入 React state供外部箭头按钮通过slidePrev()/slideNext()调用——这是外部控件 Swiper的经典写法。SwiperSlide props 与渲染函数SwiperSlide/SwiperSlide组件支持以下额外属性tag滑块 HTML 元素标签zoom是否启用 zoom 模式所需的额外包装层virtualIndex滑块的真实索引虚拟滑块场景下必须配置。SwiperSlide/SwiperSlide还支持传入渲染函数函数返回一个包含以下属性的对象isActive当前滑块处于激活状态时为trueisPrev当前滑块是激活滑块的前一张时为trueisNext当前滑块是激活滑块的后一张时为trueisVisible当前滑块可见时为true需启用watchSlidesProgressisDuplicate当前滑块是重复项时为true启用 loop 模式时出现。渲染函数示例Swiper SwiperSlide {({ isActive }) ( divCurrent slide is {isActive ? active : Slide 1}/div )} /SwiperSlide /SwiperSwiper HooksuseSwiper与useSwiperSlideSwiper hooks 是 React 下便捷获取 Swiper 实例与滑块数据的钩子。useSwiper在 Swiper 内部组件中直接获取Swiper实例// some-inner-component.jsx import { React } from react; import { useSwiper } from swiper/react; export default function SlideNextButton() { const swiper useSwiper(); return ( button onClick{() swiper.slideNext()}Slide to the next slide/button ); }useSwiperSlide供滑块内部的组件获取当前滑块数据与SwiperSlide渲染函数暴露的数据一致// some-inner-component.jsx import { React } from react; import { useSwiperSlide } from swiper/react; export default function SlideTitle() { const swiperSlide useSwiperSlide(); return ( pCurrent slide is {swiperSlide.isActive ? active : not active}/p ); }在 React 中使用 Swiper Web ComponentElementsSwiper 还提供了 Web Component 形态swiper-container/swiper-slide。由于 React 目前对自定义元素Web Components没有原生支持在 React 中使用 Swiper Element 时需要以props形式传入参数使用自定义初始化register()注册组件事件无法使用 React 的on[事件]语法必须通过.addEventListener或在初始化参数中传入on回调import { useEffect, useRef } from react; import { register } from swiper/element/bundle; register(); export default function App() { const swiperElRef useRef(null); useEffect(() { // listen for Swiper events using addEventListener swiperElRef.current.addEventListener(swiperprogress, (e) { const [swiper, progress] e.detail; console.log(progress); }); swiperElRef.current.addEventListener(swiperslidechange, (e) { console.log(slide changed); }); }, []); return ( swiper-container ref{swiperElRef} slides-per-view3 navigationtrue paginationtrue swiper-slideSlide 1/swiper-slide swiper-slideSlide 2/swiper-slide swiper-slideSlide 3/swiper-slide ... /swiper-container ); }注意事件名带swiper前缀如swiperprogress、swiperslidechange事件数据通过e.detail解构获取如const [swiper, progress] e.detail这是 Web Component 与 React 组件 API 的最大差异点。仓库实战win95 示例中的 Swiper 应用为了让上面的 API 落到真实代码我们剖析 refine 仓库中的 win95 示例。其依赖声明在 examples/win95/package.jsonswiper: ^11.1.0而 pnpm-lock.yaml 中锁定安装的版本为swiper11.1.1——这也印证了前文 CDN 示例中11大版本号的有效性。在 examples/win95/src/routes/rvc-website/home.tsx 中可以看到一套完整的外部控件驱动轮播实现导入第 6-9 行import { Controller } from swiper/modules; import { Swiper, SwiperSlide } from swiper/react; import type { Swiper as ISwiper } from swiper/types; import swiper/css;这里同时体现了本文多个要点从swiper/modules按需导入Controller模块、从swiper/react导入组件、用swiper/types标注实例类型、从swiper/css导入核心样式。轮播主体第 109-114 行Swiper modules{[Controller]} controller{{ control: controlledSwiper }} onSwiper{(swiper) setControlledSwiper(swiper)} slidesPerView{5} loop{!!titles?.length} onSwiper回调把实例存入 state对应上文onSwiperpropscontroller.control让该轮播可被外部controlledSwiper实例控制slidesPerView{5}一次展示 5 张海报loop根据数据是否为空动态开启循环模式。外部按钮第 107、139 行onClick{() controlledSwiper?.slidePrev()} onClick{() controlledSwiper?.slideNext()}这两个箭头按钮通过slidePrev()/slideNext()驱动轮播正是Swiper 方法与属性一节所讲实例方法的实战运用。样式定制第 337-341 行.swiper-slide { display: flex; align-items: center; justify-content: center; }通过 styled-components 覆盖.swiper-slide布局体现了Swiper 样式体系中核心样式与业务样式分层定制的思路。整体数据由 refine 的useListhook 提供resource: titles按created_at倒序每页 10 条即refine 数据层 Swiper 展示层的典型组合。结语本文围绕Swiper.js这一功能丰富、易于使用的轮播库覆盖了从安装下载 / CDN / npm、HTML 标记、初始化参数到方法属性、事件监听、样式体系再到 Navigation、Pagination、Scrollbar、Thumbs 四大模块的自定义以及 React 组件、props、渲染函数、hooks 与 Web Component 的完整用法并通过 refine 仓库中的 win95 示例验证了这些 API 在生产级代码中的真实形态。Swiper.js 是一个特性非常丰富的库建议在实际项目中结合其官方 API 文档持续探索更多参数与模块组合而本文讲解的模块化导入、事件绑定、外部控件驱动等模式已经足够支撑你在 refine 这类 React 项目中构建出体验良好的触摸轮播、画廊与横向内容列表。参考与延伸阅读仓库内路径本文主题文档documentation/blog/2023-12-07-swiper-js.md实战代码examples/win95/src/routes/rvc-website/home.tsx依赖声明examples/win95/package.json锁定版本pnpm-lock.yaml【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考