<!-- Slider main container -->
<div class="swiper">
<!-- Additional required wrapper -->
<div class="swiper-wrapper">
<!-- Slides -->
<div class="swiper-slide">Slide 1</div>
<div class="swiper-slide">Slide 2</div>
<div class="swiper-slide">Slide 3</div>
...
</div>
<!-- If we need pagination -->
<div class="swiper-pagination"></div>
<!-- If we need navigation buttons -->
<div class="swiper-button-prev"></div>
<div class="swiper-button-next"></div>
<!-- If we need scrollbar -->
<div class="swiper-scrollbar"></div>
</div>
Swiper 包含不同的 CSS、Less 和 SCSS 样式集
捆绑版本 CSS 样式
swiper-bundle.css
- 所有 Swiper 样式,包括所有模块样式(如导航、分页等)swiper-bundle.min.css
- 与上一个相同,但已缩小捆绑版本 CSS 样式(包导入)
swiper/css
- 所有 Swiper 样式,包括所有模块样式(如导航、分页等)swiper/css/bundle
- 与上一个相同,但已缩小核心版本和模块 CSS 样式(包导入)
swiper/css
- 仅核心 Swiper 样式swiper/css/a11y
- A11y 模块所需的样式swiper/css/autoplay
- 自动播放模块所需的样式swiper/css/controller
- 控制器模块所需的样式swiper/css/effect-cards
- 卡片效果模块所需的样式swiper/css/effect-coverflow
- Coverflow 效果模块所需的样式swiper/css/effect-creative
- 创意效果模块所需的样式swiper/css/effect-cube
- 立方体效果模块所需的样式swiper/css/effect-fade
- 淡入淡出效果模块所需的样式swiper/css/effect-flip
- 翻转效果模块所需的样式swiper/css/free-mode
- 自由模式模块所需的样式swiper/css/grid
- 网格模块所需的样式swiper/css/hash-navigation
- 哈希导航模块所需的样式swiper/css/history
- 历史记录模块所需的样式swiper/css/keyboard
- 键盘模块所需的样式swiper/css/manipulation
- 操作模块所需的样式swiper/css/mousewheel
- 鼠标滚轮模块所需的样式swiper/css/navigation
- 导航模块所需的样式swiper/css/pagination
- 分页模块所需的样式swiper/css/parallax
- 视差模块所需的样式swiper/css/scrollbar
- 滚动条模块所需的样式swiper/css/thumbs
- 缩略图模块所需的样式swiper/css/virtual
- 虚拟模块所需的样式swiper/css/zoom
- 缩放模块所需的样式Less 样式是核心版本和模块的独立样式(包导入)
swiper/less
- 仅核心 Swiper 样式swiper/less/bundle
- 所有 Swiper 样式,包括所有模块样式(如导航、分页等)swiper/less/a11y
- 无障碍访问模块所需的样式swiper/less/autoplay
- 自动播放模块所需的样式swiper/less/controller
- 控制器模块所需的样式swiper/less/effect-cards
- 卡片效果模块所需的样式swiper/less/effect-coverflow
- Coverflow 效果模块所需的样式swiper/less/effect-creative
- 创意效果模块所需的样式swiper/less/effect-cube
- 立方体效果模块所需的样式swiper/less/effect-fade
- 淡入淡出效果模块所需的样式swiper/less/effect-flip
- 翻转效果模块所需的样式swiper/less/free-mode
- 自由模式模块所需的样式swiper/less/grid
- 网格模块所需的样式swiper/less/hash-navigation
- 哈希导航模块所需的样式swiper/less/history
- 历史模块所需的样式swiper/less/keyboard
- 键盘模块所需的样式swiper/less/manipulation
- 操作模块所需的样式swiper/less/mousewheel
- 鼠标滚轮模块所需的样式swiper/less/navigation
- 导航模块所需的样式swiper/less/pagination
- 分页模块所需的样式swiper/less/parallax
- 视差模块所需的样式swiper/less/scrollbar
- 滚动条模块所需的样式swiper/less/thumbs
- 缩略图模块所需的样式swiper/less/virtual
- 虚拟模块所需的样式swiper/less/zoom
- 缩放模块所需的样式SCSS 样式也是核心版本和模块的单独样式(包导入)
swiper/scss
- 仅核心 Swiper 样式swiper/scss/bundle
- 所有 Swiper 样式,包括所有模块样式(如导航、分页等)swiper/scss/a11y
- 无障碍访问模块所需的样式swiper/scss/autoplay
- 自动播放模块所需的样式swiper/scss/controller
- 控制器模块所需的样式swiper/scss/effect-cards
- 卡片效果模块所需的样式swiper/scss/effect-coverflow
- 3D 流效果模块所需的样式swiper/scss/effect-creative
- 创意效果模块所需的样式swiper/scss/effect-cube
- 立方体效果模块所需的样式swiper/scss/effect-fade
- 淡入淡出效果模块所需的样式swiper/scss/effect-flip
- 翻转效果模块所需的样式swiper/scss/free-mode
- 自由模式模块所需的样式swiper/scss/grid
- 网格模块所需的样式swiper/scss/hash-navigation
- 哈希导航模块所需的样式swiper/scss/history
- 历史模块所需的样式swiper/scss/keyboard
- 键盘模块所需的样式swiper/scss/manipulation
- 操作模块所需的样式swiper/scss/mousewheel
- 鼠标滚轮模块所需的样式swiper/scss/navigation
- 导航模块所需的样式swiper/scss/pagination
- 分页模块所需的样式swiper/scss/parallax
- 视差模块所需的样式swiper/scss/scrollbar
- 滚动条模块所需的样式swiper/scss/thumbs
- 缩略图模块所需的样式swiper/scss/virtual
- 虚拟模块所需的样式swiper/scss/zoom
- Zoom 模块所需的样式现在,当我们有 Swiper 的 HTML 时,我们需要使用以下函数对其进行初始化
new Swiper(swiperContainer, parameters)- 使用选项初始化 swiper
例如
const swiper = new Swiper('.swiper', {
speed: 400,
spaceBetween: 100,
});
在初始化 Swiper 之后,可以在其 HTMLElement 上访问 Swiper 的实例。它是 Swiper 的 HTML 容器元素的 swiper
属性
const swiper = document.querySelector('.swiper').swiper;
// Now you can use all slider methods like
swiper.slideNext();
让我们看看所有可用参数的列表
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
a11y | 任意 | 带有 a11y 参数的对象或布尔值
| |
allowSlideNext | 布尔值 | true | 设置为 |
allowSlidePrev | 布尔值 | true | 设置为 |
allowTouchMove | 布尔值 | true | 如果为 |
autoHeight | 布尔值 | false | 设置为 |
autoplay | 任意 | 带有自动播放参数的对象或布尔值
| |
breakpoints | 对象 | 允许为不同的响应断点(屏幕大小)设置不同的参数。并非所有参数都可以在断点中更改,只有那些不需要不同布局和逻辑的参数,如
| |
breakpointsBase | 'container' | 'window' | 'window' | 断点的基准(测试版)。可以是 |
cardsEffect | 任意 | 带有卡片效果参数的对象
| |
centerInsufficientSlides | 布尔值 | false | 启用后,如果幻灯片数量少于 |
centeredSlides | 布尔值 | false | 如果为 |
centeredSlidesBounds | 布尔值 | false | 如果为 |
containerModifierClass | 字符串 | 'swiper-' | 根据不同的参数可以添加到 swiper 容器的修改器 CSS 类的开头 |
controller | 任意 | 带有控制器参数的对象或布尔值
| |
coverflowEffect | 任意 | 带有 Coverflow 效果参数的对象。
| |
createElements | 布尔值 | false | 启用后,Swiper 将自动使用 swiper-wrapper 元素包装幻灯片,并将为导航、分页和滚动条创建所需的元素(使用它们各自的参数对象或布尔值 |
creativeEffect | 任意 | 带有创意效果参数的对象
| |
cssMode | 布尔值 | false | 启用后,它将使用现代 CSS Scroll Snap API。它不支持 Swiper 的所有功能,但可能在简单配置中带来更好的性能。 启用后,不支持以下内容
如果你将它与其他效果(尤其是 3D 效果)一起使用,则需要使用
|
cubeEffect | 任意 | 带有 Cube 效果参数的对象
| |
direction | 'horizontal' | 'vertical' | “水平” | 可以是 |
edgeSwipeDetection | 字符串 | 布尔值 | false | 启用以释放 Swiper 事件,以便在应用中进行轻扫返回操作。如果设置为 |
edgeSwipeThreshold | 数字 | 20 | 从屏幕左侧开始的区域(以像素为单位),用于释放触摸事件以在应用中进行轻扫返回操作 |
effect | 字符串 | “滑动” | 过渡效果。可以是 |
enabled | 布尔值 | true | Swiper 是否最初已启用。当 Swiper 被禁用时,它将隐藏所有导航元素,并且不会对任何事件和交互做出响应 |
eventsPrefix | 字符串 | `swiper` | Swiper Element(网络组件)发出的所有 DOM 事件的事件名称前缀 |
fadeEffect | 任意 | 具有淡入淡出效果参数的对象
| |
flipEffect | 任意 | 具有翻转效果参数的对象
| |
focusableElements | 字符串 | “input、select、option、textarea、button、video、label” | 可聚焦元素的 CSS 选择器。如果此类元素“被聚焦”,则将禁用轻扫操作 |
followFinger | 布尔值 | true | 如果禁用,则仅在释放滑块时才会对其进行动画处理,当手指按住滑块时,它不会移动 |
freeMode | 任意 | 启用自由模式功能。具有自由模式参数的对象或布尔值
| |
grabCursor | 布尔值 | false | 此选项可能会稍微提高桌面可用性。如果为 |
grid | 任意 | 具有网格参数的对象,用于启用“多行”滑块。
| |
hashNavigation | 任意 | 启用哈希 URL 导航以用于幻灯片。具有哈希导航参数的对象或布尔值
| |
height | null | 数字 | null | Swiper 高度(以像素为单位)。此参数允许强制设置 Swiper 高度。仅当在隐藏时初始化 Swiper 以及在 SSR 和测试环境中进行正确的 Swiper 初始化时才有用
|
history | 任意 | 启用历史记录推送状态,其中每张幻灯片都有自己的 URL。在此参数中,您必须指定主幻灯片 URL,如 具有历史记录导航参数的对象或布尔值
| |
init | 布尔值 | true | 当您创建实例时,是否应自动初始化 Swiper。如果禁用,则需要通过调用 |
initialSlide | 数字 | 0 | 初始幻灯片的索引号。 |
injectStyles | string[] | 将文本样式注入到 Shadow DOM 中。仅适用于 Swiper Element | |
injectStylesUrls | string[] | 将样式 | |
keyboard | 任意 | 启用通过键盘导航幻灯片。具有键盘参数的对象或布尔值
| |
lazyPreloadPrevNext | 数字 | 0 | 要预加载的下一张和上一张幻灯片数量。仅适用于使用延迟加载时。 |
lazyPreloaderClass | 字符串 | 'swiper-lazy-preloader' | 延迟预加载器的 CSS 类名 |
longSwipes | 布尔值 | true | 如果要禁用长滑动,请设置为 |
longSwipesMs | 数字 | 300 | 在长滑动期间触发滑动到下一张/上一张幻灯片的最小持续时间(以毫秒为单位) |
longSwipesRatio | 数字 | 0.5 | 在长滑动期间触发滑动到下一张/上一张幻灯片的比率 |
loop | 布尔值 | false | 设置为 由于循环模式的工作原理(它将重新排列幻灯片),幻灯片的总数必须
|
loopAddBlankSlides | 布尔值 | true | 如果您使用 Grid 或 |
loopAdditionalSlides | 数字 | 0 | 允许增加循环幻灯片数量 |
loopPreventsSliding | 布尔值 | true | 如果启用,则在循环模式下滑块动画播放时,slideNext/Prev 将不起作用 |
maxBackfaceHiddenSlides | 数字 | 10 | 如果幻灯片的总数少于此处指定的值,则 Swiper 将在幻灯片元素上启用
|
模块 | any[] | 带有 Swiper 模块的数组
| |
mousewheel | 任意 | 使用鼠标滚轮浏览幻灯片。带有鼠标滚轮参数的对象或布尔值
| |
navigation | 任意 | 带有导航参数的对象或布尔值
| |
nested | 布尔值 | false | 在 Swiper 上设置为 |
noSwiping | 布尔值 | true | 在与 |
noSwipingClass | 字符串 | 'swiper-no-swiping' | 指定 |
noSwipingSelector | 字符串 | 可用于代替 | |
normalizeSlideIndex | 布尔值 | true | 标准化幻灯片索引。 |
observeParents | 布尔值 | false | 如果您还需要监视 Swiper 父元素的变动,则设置为 |
observeSlideChildren | 布尔值 | false | 如果您还需要监视 Swiper 幻灯片子元素的变动,则设置为 |
observer | 布尔值 | false | 设置为 |
on | 对象 | 注册事件处理程序 | |
onAny | function(handler) | 添加将在所有事件上触发的事件侦听器
| |
oneWayMovement | 布尔值 | false | 启用后,无论滑动方向如何,都只会向前滑动幻灯片(单向) |
pagination | 任意 | 带有分页参数的对象或布尔值
| |
parallax | 任意 | 带有视差参数的对象或布尔值
| |
passiveListeners | 布尔值 | true | 在可能的情况下,默认情况下将使用被动事件侦听器来提高移动设备上的滚动性能。但是,如果您需要使用 |
preventClicks | 布尔值 | true | 设置为 |
preventClicksPropagation | 布尔值 | true | 在滑动期间将点击事件传播到链接上设置为 |
preventInteractionOnTransition | 布尔值 | false | 启用后,在过渡期间不允许通过滑动或导航/分页按钮更改幻灯片 |
resistance | 布尔值 | true | 如果您想禁用抗性边界,请将其设置为 |
resistanceRatio | 数字 | 0.85 | 此选项允许您控制抗性比率 |
resizeObserver | 布尔值 | true | 启用后,它将在 swiper 容器上使用 ResizeObserver(如果浏览器支持)来检测容器大小调整(而不是监视窗口大小调整) |
rewind | 布尔值 | false | 设置为
|
roundLengths | 布尔值 | false | 设置为 |
runCallbacksOnInit | 布尔值 | true | 在 swiper 初始化时触发过渡/幻灯片更改/开始/结束事件。如果您的 initialSlide 不为 0,或者您使用循环模式,则会在初始化时触发此类事件 |
scrollbar | 任意 | 带滚动条参数的对象或布尔值
| |
setWrapperSize | 布尔值 | false | 启用此选项,插件将在 swiper wrapper 上设置宽度/高度,等于所有幻灯片的总大小。主要用作兼容性后备选项,适用于不支持 flexbox 布局的浏览器 |
shortSwipes | 布尔值 | true | 如果您想禁用短滑动,请将其设置为 |
simulateTouch | 布尔值 | true | 如果为 |
slideActiveClass | 字符串 | 'swiper-slide-active' | 当前活动幻灯片的 CSS 类名
|
slideBlankClass | 字符串 | 'swiper-slide-blank' | 循环模式添加的空白幻灯片的 CSS 类名(当启用
|
slideClass | 字符串 | 'swiper-slide' | 幻灯片的 CSS 类名
|
slideFullyVisibleClass | 字符串 | 'swiper-slide-fully-visible' | 完全(当整个幻灯片在视口中)可见幻灯片的 CSS 类名
|
slideNextClass | 字符串 | 'swiper-slide-next' | 紧随当前活动幻灯片之后的幻灯片的 CSS 类名
|
slidePrevClass | 字符串 | 'swiper-slide-prev' | 紧靠当前活动幻灯片之前的幻灯片的 CSS 类名
|
slideToClickedSlide | 布尔值 | false | 设置为 |
slideVisibleClass | 字符串 | 'swiper-slide-visible' | 当前/部分可见幻灯片的 CSS 类名
|
slidesOffsetAfter | 数字 | 0 | 在容器末尾(所有幻灯片之后)添加(以像素为单位)附加幻灯片偏移量 |
slidesOffsetBefore | 数字 | 0 | 在容器开头(所有幻灯片之前)添加(以像素为单位)附加幻灯片偏移量 |
slidesPerGroup | 数字 | 1 | 设置幻灯片数量以定义和启用组滑动。与 slidesPerView > 1 一起使用很有用 |
slidesPerGroupAuto | 布尔值 | false | 此参数仅用于 |
slidesPerGroupSkip | 数字 | 0 | 该参数的工作方式如下:如果 如果 |
slidesPerView | number | 'auto' | 1 | 每个视图的幻灯片数量(在滑块容器上同时可见的幻灯片)。
|
spaceBetween | string | number | 0 | 幻灯片之间的距离(以像素为单位)。
|
speed | 数字 | 300 | 幻灯片之间过渡的持续时间(以毫秒为单位) |
swipeHandler | 任意 | null | 带有分页容器的 CSS 选择器或 HTML 元素的字符串,该容器将作为仅可用于滑动的可用处理程序 |
swiperElementNodeName | 字符串 | 'SWIPER-CONTAINER' | swiper 元素节点名称的名称;用于检测 Web 组件渲染 |
阈值 | 数字 | 5 | 以 px 为单位的阈值。如果“触摸距离”低于此值,则 swiper 将不会移动 |
缩略图 | 任意 | 包含缩略图组件参数的对象
| |
触摸角度 | 数字 | 45 | 触发触摸移动的允许角度(以度为单位) |
触摸事件目标 | 'container' | 'wrapper' | 'wrapper' | 侦听触摸事件的目标元素。可以是 |
触摸移动阻止传播 | 布尔值 | false | 如果启用,则将停止“touchmove”的传播 |
触摸比率 | 数字 | 1 | 触摸比率 |
边缘触摸释放 | 布尔值 | false | 启用此功能可在滑块边缘位置(开始、结束)释放触摸事件,以便进一步滚动页面。此功能仅适用于“触摸”事件(而不是指针事件),因此它适用于 iOS/Android 设备,但不适用于具有指针事件的 Windows 设备。此外, |
触摸开始强制阻止默认 | 布尔值 | false | 强制始终阻止 |
触摸开始阻止默认 | 布尔值 | true | 如果禁用,则不会阻止 |
唯一的导航元素 | 布尔值 | true | 如果启用(默认情况下)并且导航元素的参数作为字符串传递(如 |
窗口调整大小时更新 | 布尔值 | true | Swiper 将在窗口调整大小时(方向更改)重新计算幻灯片位置 |
网址 | null | 字符串 | null | 当在服务器端渲染并启用历史记录时,需要此功能来检测活动幻灯片 |
用户代理 | null | 字符串 | null | 用户代理字符串。在服务器端渲染时,需要此功能来检测浏览器/设备 |
虚拟 | 任意 | 启用虚拟幻灯片功能。包含虚拟幻灯片参数的对象或布尔值
| |
虚拟翻译 | 布尔值 | false | 启用此选项,swiper 将像往常一样操作,但它不会移动,包装器上的真实平移值不会被设置。当您可能需要创建自定义幻灯片过渡时,此功能非常有用 |
观察溢出 | 布尔值 | true | 启用此功能后,如果幻灯片不足以滑动,则 Swiper 将被禁用并隐藏导航按钮。 |
观察幻灯片进度 | 布尔值 | false | 启用此功能可计算每个幻灯片的进度和可见性(视口中的幻灯片将具有额外的可见类) |
宽度 | null | 数字 | null | Swiper 宽度(以像素为单位)。此参数允许强制设置 Swiper 宽度。仅在 Swiper 在隐藏状态下初始化时,以及在 SSR 和测试环境中,为正确初始化 Swiper 时才很有用
|
wrapperClass | 字符串 | 'swiper-wrapper' | 幻灯片包装器的 CSS 类名
|
zoom | 任意 | 启用缩放功能。包含缩放参数的对象或布尔值
|
在初始化 Slider 后,我们会在变量中获得其已初始化的实例(如上例中的 swiper
变量),其中包含有用的方法和属性
属性 | ||
---|---|---|
swiper.a11y | 任意 | |
swiper.activeIndex | 数字 | 当前活动幻灯片的索引号
|
swiper.allowSlideNext | 布尔值 | 通过将 |
swiper.allowSlidePrev | 布尔值 | 通过将 |
swiper.allowTouchMove | 布尔值 | 通过将 |
swiper.animating | 布尔值 | 如果 swiper 正在过渡,则为 |
swiper.autoplay | 任意 | |
swiper.cardsEffect | 任意 | |
swiper.clickedIndex | 数字 | 上次单击的幻灯片的索引号 |
swiper.clickedSlide | HTMLElement | 指向上次单击的幻灯片(HTMLElement)的链接 |
swiper.controller | 任意 | |
swiper.coverflowEffect | 任意 | |
swiper.creativeEffect | 任意 | |
swiper.cubeEffect | 任意 | |
swiper.defaults | 任意 | Swiper 默认选项 |
swiper.el | HTMLElement | Slider 容器 HTML 元素 |
swiper.extendedDefaults | 任意 | 包含全局 Swiper 扩展选项的对象 |
swiper.fadeEffect | 任意 | |
swiper.flipEffect | 任意 | |
swiper.freeMode | 任意 | |
swiper.hashNavigation | 任意 | |
swiper.height | 数字 | 容器高度 |
swiper.history | 任意 | |
swiper.isBeginning | 布尔值 | 如果滑块处于最“左”/“上”位置,则为 |
swiper.isEnd | 布尔值 | 如果滑块处于最“右”/“下”位置,则为 |
swiper.isLocked | 布尔值 | 如果幻灯片被“锁定”(通过 |
swiper.keyboard | 任意 | |
swiper.mousewheel | 任意 | |
swiper.navigation | 任意 | |
swiper.originalParams | 任意 | 包含原始初始化参数的对象 |
swiper.pagination | 任意 | |
swiper.parallax | 任意 | |
swiper.params | 任意 | 包含已传递初始化参数的对象 |
swiper.previousIndex | 数字 | 先前活动幻灯片的索引号 |
swiper.progress | 数字 | 包装器平移的当前进度(从 0 到 1) |
swiper.realIndex | 数字 | 在循环模式下考虑重新排列的幻灯片的当前活动幻灯片的索引号 |
swiper.scrollbar | 任意 | |
swiper.slides | HTMLElement[] | 幻灯片 HTML 元素的数组。要获取特定的幻灯片 HTMLElement,请使用 |
swiper.snapGrid | number[] | 幻灯片捕捉网格 |
swiper.snapIndex | 数字 |
|
swiper.swipeDirection | 'prev' | 'next' | 滑动方向 |
swiper.thumbs | 任意 | |
swiper.touches | 对象 | 包含以下触摸事件属性的对象
|
swiper.translate | 数字 | 包装器平移的当前值 |
swiper.virtual | 任意 | |
swiper.width | 数字 | 容器的宽度 |
swiper.wrapperEl | HTMLElement | 包装器 HTML 元素 |
swiper.zoom | 任意 | |
方法 | ||
swiper.attachEvents() | 再次附加所有事件侦听器 | |
swiper.changeDirection(direction, needUpdate) | 将滑块方向从水平更改为垂直,反之亦然。
| |
swiper.changeLanguageDirection(direction) | 更改滑块语言
| |
swiper.destroy(deleteInstance, cleanStyles) | 销毁滑块实例并分离所有事件侦听器
| |
swiper.detachEvents() | 分离所有事件侦听器 | |
swiper.disable() | 禁用 Swiper(如果已启用)。当 Swiper 被禁用时,它将隐藏所有导航元素,并且不会响应任何事件和交互 | |
swiper.emit(事件, 参数) | 在实例上触发事件 | |
swiper.enable() | 启用 Swiper(如果已禁用) | |
swiper.extendDefaults(选项) | 扩展全局 Swiper 默认值 | |
swiper.getTranslate() | 获取 swiper 包装器 css3 转换平移的当前值 | |
swiper.init(el) | 初始化滑块 | |
swiper.off(事件, 处理程序) | 删除事件处理程序 | |
swiper.offAny(处理程序) | 删除将在所有事件上触发的事件侦听器 | |
swiper.on(事件, 处理程序) | 添加事件处理程序 | |
swiper.onAny(处理程序) | 添加将在所有事件上触发的事件侦听器 | |
swiper.once(事件, 处理程序) | 添加将在触发后删除的事件处理程序 | |
swiper.setGrabCursor() | 设置抓取光标 | |
swiper.setProgress(进度, 速度) | 设置 Swiper 平移进度(从 0 到 1)。其中 0 - 其在第一张幻灯片上的初始位置(偏移量),1 - 其在最后一张幻灯片上的最大位置(偏移量)
| |
swiper.setTranslate(平移) | 为 swiper 包装器设置自定义 css3 转换的平移值 | |
swiper.slideNext(速度, 运行回调) | 运行过渡到下一张幻灯片。
| |
swiper.slidePrev(speed, runCallbacks) | 运行过渡到上一张幻灯片。
| |
swiper.slideReset(speed, runCallbacks) | 将 swiper 位置重置为当前活动幻灯片,持续时间等于“speed”参数。
| |
swiper.slideTo(index, speed, runCallbacks) | 运行过渡到幻灯片,其索引号等于“index”参数,持续时间等于“speed”参数。
| |
swiper.slideToClosest(speed, runCallbacks) | 将 swiper 位置重置为最接近的幻灯片/捕捉点,持续时间等于“speed”参数。
| |
swiper.slideToLoop(index, speed, runCallbacks) | 与 .slideTo 相同,但用于启用循环的情况。因此,此方法将滑动到 realIndex 与传递的索引匹配的幻灯片
| |
swiper.slidesPerViewDynamic() | 获取按视图动态计算的幻灯片数量,仅当 slidesPerView 设置为 | |
swiper.translateTo(translate, speed, runCallbacks, translateBounds) | 为 swiper 包装器设置自定义 css3 transform 的 translate 值
| |
swiper.unsetGrabCursor() | 取消抓取光标 | |
swiper.update() | 手动添加/删除幻灯片后,或隐藏/显示幻灯片后,或使用 Swiper 对 Swiper 进行任何自定义 DOM 修改后,您应该调用它。此方法还包括以下方法的子调用,您可以单独使用这些方法 | |
swiper.updateAutoHeight(speed) | 强制 swiper 更新其高度(当启用 autoHeight 时),持续时间等于“speed”参数
| |
swiper.updateProgress() | 重新计算 swiper 进度 | |
swiper.updateSize() | 重新计算 swiper 容器的大小 | |
swiper.updateSlides() | 重新计算幻灯片数量及其偏移量。在使用 JavaScript 添加/删除幻灯片后很有用 | |
swiper.updateSlidesClasses() | 更新幻灯片和项目符号上的活动/上一个/下一个类 | |
swiper.use(modules) | 在运行时在 Swiper 上安装模块。 |
Swiper 带有一堆有用的事件,您可以监听。可以通过两种方式分配事件
在 swiper 初始化时使用 on
参数
const swiper = new Swiper('.swiper', {
// ...
on: {
init: function () {
console.log('swiper initialized');
},
},
});
在 swiper 初始化后使用 on
方法。
const swiper = new Swiper('.swiper', {
// ...
});
swiper.on('slideChange', function () {
console.log('slide changed');
});
this
关键字始终指向 Swiper 实例名称 | 参数 | 描述 |
---|---|---|
activeIndexChange | (swiper) | 活动索引更改时触发事件 |
afterInit | (swiper) | 初始化后立即触发事件 |
beforeDestroy | (swiper) | Swiper 销毁前立即触发事件 |
beforeInit | (swiper) | 初始化前立即触发事件 |
beforeLoopFix | (swiper) | 在“循环修复”之前立即触发事件 |
beforeResize | (swiper) | 在调整大小处理程序之前触发事件 |
beforeSlideChangeStart | (swiper) | 在幻灯片更改过渡开始之前触发事件 |
beforeTransitionStart | (swiper, speed, internal) | 过渡开始前触发事件 |
breakpoint | (swiper, breakpointParams) | 在断点更改时触发事件 |
changeDirection | (swiper) | 在方向更改时触发事件 |
click | (swiper, event) | 当用户点击/轻触 Swiper 时触发事件。接收 |
destroy | (swiper) | 在 swiper 销毁时触发事件 |
doubleClick | (swiper, event) | 当用户在 Swiper 上双击/轻触时触发事件 |
doubleTap | (swiper, event) | 当用户双击 Swiper 的容器时触发事件。接收 |
fromEdge | (swiper) | 当 Swiper 从开始或结束位置移动时触发事件 |
init | (swiper) | Swiper 初始化后立即触发。
|
lock | (swiper) | 当 swiper 被锁定时(当启用 |
loopFix | (swiper) | “循环修复”后触发事件 |
momentumBounce | (swiper) | 动量反弹时触发事件 |
observerUpdate | (swiper) | 如果启用了观察器并且它检测到 DOM 突变,则触发事件 |
orientationchange | (swiper) | 方向改变时触发事件(例如,横向 -> 纵向) |
progress | (swiper, progress) | Swiper 进度更改时触发事件,作为参数,它接收始终在 0 到 1 之间的进度 |
reachBeginning | (swiper) | Swiper 到达其开头(初始位置)时触发事件 |
reachEnd | (swiper) | Swiper 到达最后一张幻灯片时触发事件 |
realIndexChange | (swiper) | 实际索引更改时触发事件 |
resize | (swiper) | 在 swiper 的 onresize 操作之前,窗口调整大小时触发事件 |
setTransition | (swiper, transition) | 每次 swiper 启动动画时触发事件。接收当前过渡持续时间(以毫秒为单位)作为参数 |
setTranslate | (swiper, translate) | 当 swiper 的包装器改变其位置时触发事件。接收当前平移值作为参数 |
slideChange | (swiper) | 当前活动幻灯片更改时触发事件 |
slideChangeTransitionEnd | (swiper) | 动画到其他幻灯片(下一个或上一个)后触发事件。 |
slideChangeTransitionStart | (swiper) | 动画到其他幻灯片(下一个或上一个)开始时触发事件。 |
slideNextTransitionEnd | (swiper) | 与 “slideChangeTransitionEnd” 相同,但仅适用于 “向前” 方向 |
slideNextTransitionStart | (swiper) | 与 “slideChangeTransitionStart” 相同,但仅适用于 “向前” 方向 |
slidePrevTransitionEnd | (swiper) | 与 “slideChangeTransitionEnd” 相同,但仅适用于 “向后” 方向 |
slidePrevTransitionStart | (swiper) | 与 “slideChangeTransitionStart” 相同,但仅适用于 “向后” 方向 |
slideResetTransitionEnd | (swiper) | 动画结束时触发事件,将幻灯片重置为当前幻灯片 |
slideResetTransitionStart | (swiper) | 动画开始时触发事件,将幻灯片重置为当前幻灯片 |
sliderFirstMove | (swiper, event) | 第一次触摸/拖动移动时触发事件 |
sliderMove | (swiper, event) | 当用户触摸并手指在 Swiper 上移动并移动它时触发事件。接收 |
slidesGridLengthChange | (swiper) | 幻灯片网格更改时触发事件 |
slidesLengthChange | (swiper) | 幻灯片数量更改时触发事件 |
slidesUpdated | (swiper) | 幻灯片及其大小计算并更新后触发事件 |
snapGridLengthChange | (swiper) | 捕捉网格更改时触发事件 |
snapIndexChange | (swiper) | 捕捉索引更改时触发事件 |
轻触 | (swiper, event) | 当用户点击/轻触 Swiper 时触发事件。接收 |
toEdge | (swiper) | 当 Swiper 滑动至起始或结束位置时触发事件 |
touchEnd | (swiper, event) | 当用户释放 Swiper 时触发事件。接收 |
touchMove | (swiper, event) | 当用户触碰并滑动手指操作 Swiper 时触发事件。接收 |
touchMoveOpposite | (swiper, event) | 当用户触碰并滑动手指操作 Swiper 时触发事件,且滑动方向与 direction 参数相反。接收 |
touchStart | (swiper, event) | 当用户触碰 Swiper 时触发事件。接收 |
transitionEnd | (swiper) | 过渡结束后触发事件。 |
transitionStart | (swiper) | 过渡开始时触发事件。 |
unlock | (swiper) | 当 swiper 解锁时触发事件(当启用 |
update | (swiper) | 调用 swiper.update() 后触发事件 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
disabledClass | 字符串 | 'swiper-button-disabled' | 当导航按钮变为禁用状态时添加的 CSS 类名 |
enabled | 布尔值 | 与断点一起使用的布尔属性,用于在特定断点上启用/禁用导航 | |
字符串 | 'swiper-button-hidden' | 当导航按钮变为隐藏状态时添加的 CSS 类名 | |
hideOnClick | 布尔值 | false | 在点击滑块容器后切换导航按钮的可见性 |
lockClass | 字符串 | 'swiper-button-lock' | 当导航按钮被禁用时添加的 CSS 类名 |
navigationDisabledClass | 字符串 | 'swiper-navigation-disabled' | 当导航被断点禁用时添加到 swiper 容器上的 CSS 类名 |
nextEl | 任意 | null | 点击后将作为“下一步”按钮工作的元素的 CSS 选择器或 HTML 元素的字符串 |
prevEl | 任意 | null | 点击后将作为“上一步”按钮工作的元素的 CSS 选择器或 HTML 元素的字符串 |
属性 | ||
---|---|---|
swiper.nextEl | HTMLElement | “下一步”导航按钮的 HTMLElement |
swiper.prevEl | HTMLElement | “上一步”导航按钮的 HTMLElement |
方法 | ||
swiper.destroy() | 销毁导航 | |
swiper.init() | 初始化导航 | |
swiper.update() | 更新导航按钮状态(启用/禁用) |
名称 | 参数 | 描述 |
---|---|---|
navigationHide | (swiper) | 导航隐藏时触发事件 |
navigationNext | (swiper) | 点击导航下一个按钮时触发事件 |
navigationPrev | (swiper) | 点击导航上一个按钮时触发事件 |
navigationShow | (swiper) | 导航显示时触发事件 |
{
--swiper-navigation-size: 44px;
--swiper-navigation-top-offset: 50%;
--swiper-navigation-sides-offset: 10px;
--swiper-navigation-color: var(--swiper-theme-color);
}
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
bulletActiveClass | 字符串 | 'swiper-pagination-bullet-active' | 当前活动分页项目符号的 CSS 类名 |
bulletClass | 字符串 | 'swiper-pagination-bullet' | 单个分页项目符号的 CSS 类名 |
bulletElement | 字符串 | 'span' | 定义哪个 HTML 标记将用于表示单个分页项目符号。仅适用于 |
clickable | 布尔值 | false | 如果为 |
clickableClass | 字符串 | 'swiper-pagination-clickable' | 当分页可点击时设置的 CSS 类名 |
currentClass | 字符串 | 'swiper-pagination-current' | "fraction" 分页中当前活动索引的元素的 CSS 类名 |
dynamicBullets | 布尔值 | false | 如果你使用带有大量幻灯片的项目符号分页,最好启用此功能。因此,它将同时保持只有几个项目符号可见。 |
dynamicMainBullets | 数字 | 1 | 启用 |
el | 任意 | null | 带有分页容器的 CSS 选择器或 HTML 元素的字符串 |
enabled | 布尔值 | 与断点一起使用的布尔属性,用于在特定断点上启用/禁用分页 | |
formatFractionCurrent | function(number) | 格式化分数分页当前数字。函数接收当前数字,你需要返回格式化的值 | |
formatFractionTotal | function(number) | 格式化分数分页总数。函数接收总数,您需要返回格式化值 | |
字符串 | 'swiper-pagination-hidden' | 当分页变为非活动状态时的分页 CSS 类名 | |
hideOnClick | 布尔值 | true | 在单击滑块容器后切换(隐藏/显示)分页容器可见性 |
horizontalClass | 字符串 | 'swiper-pagination-horizontal' | 在水平 Swiper 中设置到分页的 CSS 类名 |
lockClass | 字符串 | 'swiper-pagination-lock' | 当分页被禁用时设置到分页的 CSS 类名 |
modifierClass | 字符串 | 'swiper-pagination-' | 将根据参数添加到分页的修饰符 CSS 类名的开头 |
paginationDisabledClass | 字符串 | 'swiper-pagination-disabled' | 当分页被断点禁用时添加到 swiper 容器和分页元素的 CSS 类名 |
progressbarFillClass | 字符串 | 'swiper-pagination-progressbar-fill' | 分页进度条填充元素的 CSS 类名 |
progressbarOpposite | 布尔值 | false | 使分页进度条与 Swiper 的 |
progressbarOppositeClass | 字符串 | 'swiper-pagination-progressbar-opposite' | 分页进度条相反的 CSS 类名 |
renderBullet | function(index, className) | 此参数允许完全自定义分页项目符号,您需要在此处传递一个函数,该函数接受分页项目符号的
| |
renderCustom | function(swiper, current, total) | 此参数对于
| |
renderFraction | function(currentClass, totalClass) | 此参数允许自定义“分数”分页 html。仅适用于
| |
renderProgressbar | function(progressbarFillClass) | 此参数允许自定义“进度”分页。仅适用于
| |
totalClass | 字符串 | 'swiper-pagination-total' | “分数”分页中具有“快照”总数的元素的 CSS 类名 |
type | 'progressbar' | 'bullets' | 'fraction' | 'custom' | 'bullets' | 带有分页类型的字符串。可以是 |
verticalClass | 字符串 | 'swiper-pagination-vertical' | 垂直 Swiper 中分页设置的 CSS 类名 |
属性 | ||
---|---|---|
swiper.bullets | HTMLElement[] | 分页项目 HTML 元素的数组。若要获取特定的幻灯片 HTMLElement,请使用 |
swiper.el | HTMLElement | 分页容器元素的 HTMLElement |
方法 | ||
swiper.destroy() | 销毁分页 | |
swiper.init() | 初始化分页 | |
swiper.render() | 呈现分页布局 | |
swiper.update() | 更新分页状态(启用/禁用/激活) |
名称 | 参数 | 描述 |
---|---|---|
paginationHide | (swiper) | 在隐藏分页时触发事件 |
paginationRender | (swiper, paginationEl) | 在呈现分页后触发事件 |
paginationShow | (swiper) | 在显示分页时触发事件 |
paginationUpdate | (swiper, paginationEl) | 在更新分页时触发事件 |
{
--swiper-pagination-color: var(--swiper-theme-color);
--swiper-pagination-left: auto;
--swiper-pagination-right: 8px;
--swiper-pagination-bottom: 8px;
--swiper-pagination-top: auto;
--swiper-pagination-fraction-color: inherit;
--swiper-pagination-progressbar-bg-color: rgba(0, 0, 0, 0.25);
--swiper-pagination-progressbar-size: 4px;
--swiper-pagination-bullet-size: 8px;
--swiper-pagination-bullet-width: 8px;
--swiper-pagination-bullet-height: 8px;
--swiper-pagination-bullet-inactive-color: #000;
--swiper-pagination-bullet-inactive-opacity: 0.2;
--swiper-pagination-bullet-opacity: 1;
--swiper-pagination-bullet-horizontal-gap: 4px;
--swiper-pagination-bullet-vertical-gap: 6px;
}
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
dragClass | 字符串 | 'swiper-scrollbar-drag' | 滚动条可拖动元素的 CSS 类 |
dragSize | number | 'auto' | 'auto' | 滚动条可拖动元素的大小(以像素为单位) |
draggable | 布尔值 | false | 设置为 |
el | 任意 | null | 带有滚动条的容器的 CSS 选择器或 HTML 元素的字符串。 |
enabled | 布尔值 | 与断点一起使用的布尔属性,以在特定断点上启用/禁用滚动条。 | |
hide | 布尔值 | true | 在用户交互后自动隐藏滚动条 |
horizontalClass | 字符串 | 'swiper-scrollbar-horizontal' | 水平 Swiper 中滚动条设置的 CSS 类名 |
lockClass | 字符串 | 'swiper-scrollbar-lock' | 禁用时滚动条元素的附加 CSS 类 |
scrollbarDisabledClass | 字符串 | 'swiper-scrollbar-disabled' | 当滚动条被断点禁用时,添加到 Swiper 容器和滚动条元素的 CSS 类名 |
snapOnRelease | 布尔值 | false | 设置为 |
verticalClass | 字符串 | 'swiper-scrollbar-vertical' | 在垂直 Swiper 中设置的滚动条 CSS 类名 |
属性 | ||
---|---|---|
swiper.dragEl | HTMLElement | 滚动条可拖动处理程序元素的 HTMLElement |
swiper.el | HTMLElement | 滚动条容器元素的 HTMLElement |
方法 | ||
swiper.destroy() | 销毁滚动条 | |
swiper.init() | 初始化滚动条 | |
swiper.setTranslate() | 更新滚动条平移 | |
swiper.updateSize() | 更新滚动条轨道和处理程序大小 |
名称 | 参数 | 描述 |
---|---|---|
scrollbarDragEnd | (swiper, event) | 事件将在可拖动滚动条拖动结束时触发 |
scrollbarDragMove | (swiper, event) | 事件将在可拖动滚动条拖动移动时触发 |
scrollbarDragStart | (swiper, event) | 事件将在可拖动滚动条拖动开始时触发 |
{
--swiper-scrollbar-border-radius: 10px;
--swiper-scrollbar-top: auto;
--swiper-scrollbar-bottom: 4px;
--swiper-scrollbar-left: auto;
--swiper-scrollbar-right: 4px;
--swiper-scrollbar-sides-offset: 1%;
--swiper-scrollbar-bg-color: rgba(0, 0, 0, 0.1);
--swiper-scrollbar-drag-bg-color: rgba(0, 0, 0, 0.5);
--swiper-scrollbar-size: 4px;
}
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
delay | 数字 | 3000 | 过渡之间的延迟(以毫秒为单位)。如果未指定此参数,则自动播放将被禁用 如果您需要为特定幻灯片指定不同的延迟,可以使用幻灯片上的
|
disableOnInteraction | 布尔值 | true | 设置为 |
pauseOnMouseEnter | 布尔值 | false | 启用后,当指针(鼠标)进入 Swiper 容器时,自动播放将暂停。 |
reverseDirection | 布尔值 | false | 启用反向自动播放 |
stopOnLastSlide | 布尔值 | false | 启用此参数,当自动播放到达最后一张幻灯片时,它将停止(在循环模式下无效) |
waitForTransition | 布尔值 | true | 启用后,自动播放将等待包装器过渡继续。当使用虚拟平移时,您的滑块可能没有过渡,在这种情况下可以禁用此功能 |
属性 | ||
---|---|---|
swiper.paused | 布尔值 | 是否暂停自动播放 |
swiper.running | 布尔值 | 是否启用并运行自动播放 |
swiper.timeLeft | 数字 | 如果暂停自动播放,它将包含切换到下一张幻灯片之前剩余的时间(以毫秒为单位) |
方法 | ||
swiper.pause() | 暂停自动播放 | |
swiper.resume() | 恢复自动播放 | |
swiper.start() | 开始自动播放 | |
swiper.stop() | 停止自动播放 |
名称 | 参数 | 描述 |
---|---|---|
autoplay | (swiper) | 当幻灯片通过自动播放更改时将触发事件 |
autoplayPause | (swiper) | 在自动播放暂停时将触发事件 |
autoplayResume | (swiper) | 在自动播放恢复时将触发事件 |
autoplayStart | (swiper) | 在自动播放开始时将触发事件 |
autoplayStop | (swiper) | 在自动播放停止时将触发事件 |
autoplayTimeLeft | (swiper, timeLeft, percentage) | 在启用自动播放时,事件会持续触发。它包含切换到下一张幻灯片之前剩余的时间(以毫秒为单位)以及该时间相对于自动播放延迟的百分比 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | 布尔值 | false | 是否启用自由模式 |
minimumVelocity | 数字 | 0.02 | 触发自由模式动量所需的最小 touchmove 速度 |
momentum | 布尔值 | true | 如果启用,则在释放幻灯片后,它将继续移动一段时间 |
momentumBounce | 布尔值 | true | 如果要在自由模式中禁用动量反弹,请将其设置为 |
momentumBounceRatio | 数字 | 1 | 较高的值会产生更大的动量反弹效果 |
momentumRatio | 数字 | 1 | 释放滑块后,较高的值会产生更大的动量距离 |
momentumVelocityRatio | 数字 | 1 | 释放滑块后,较高的值会产生更大的动量速度 |
sticky | 布尔值 | false | 设置为启用以启用在自由模式下捕捉幻灯片位置 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
fill | 'row' | 'column' | “列” | 可以是
|
行 | 数字 | 1 | 幻灯片行数,用于多行布局 |
操作模块添加有用的 Swiper 方法来操作幻灯片。仅在 Swiper Core 版本中使用它才有意义,不打算与 Swiper React 或 Vue 一起使用。
方法 | ||
---|---|---|
swiper.addSlide(index, slides) | 将新幻灯片添加到所需索引。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如
| |
swiper.appendSlide(slides) | 将新幻灯片添加到末尾。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如
| |
swiper.prependSlide(slides) | 将新幻灯片添加到开头。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如
| |
swiper.removeAllSlides() | 移除所有幻灯片 | |
swiper.removeSlide(slideIndex) | 移除选定的幻灯片。slideIndex 可以是包含要移除的幻灯片索引的数字或包含索引的数组。
|
Swiper 支持 swiper/slides 嵌套元素的视差过渡效果。支持两种类型的视差元素
swiper
的直接子元素。此类元素的视差效果将取决于滑块的总体进度。适用于视差背景要启用视差效果,您需要使用传递的 parallax:true
参数初始化 Swiper,并将以下属性(或混合)之一添加到所需元素
data-swiper-parallax
- 启用 transform-translate 视差过渡。此属性可以接受
number
- 以像素为单位的值(如上例中的标题、副标题),用于根据进度移动元素。在这种情况下,此类元素将根据幻灯片位置(下一个或上一个)以 ± 此值以像素为单位移动percentage
- (如“parallax-bg”)根据进度和大小移动元素。在这种情况下,此类元素将根据幻灯片位置(下一个或上一个)以 ± 其大小的此百分比(水平方向的宽度,垂直方向的高度)移动。因此,如果元素的宽度为 400px,并且您指定 data-swiper-parallax="50%",那么它将以 ± 200px 移动data-swiper-parallax-x
- 与 x 轴方向相同data-swiper-parallax-y
- 与 y 轴方向相同data-swiper-parallax-scale
- 视差元素处于“非活动”(不在活动幻灯片上)状态时的缩放比例data-swiper-parallax-opacity
- 视差元素处于“非活动”(不在活动幻灯片上)状态时的不透明度data-swiper-parallax-duration
- 视差元素的自定义过渡持续时间<div class="swiper">
<!-- Parallax background element -->
<div
class="parallax-bg"
style="background-image:url(path/to/image.jpg)"
data-swiper-parallax="-23%"
></div>
<div class="swiper-wrapper">
<div class="swiper-slide">
<!-- Each slide has parallax title -->
<div class="title" data-swiper-parallax="-100">Slide 1</div>
<!-- Parallax subtitle -->
<div class="subtitle" data-swiper-parallax="-200">Subtitle</div>
<!-- And parallax text with custom transition duration -->
<div
class="text"
data-swiper-parallax="-300"
data-swiper-parallax-duration="600"
>
<p>Lorem ipsum dolor sit amet, ...</p>
</div>
<!-- Opacity parallax -->
<div data-swiper-parallax-opacity="0.5">I will change opacity</div>
<!-- Scale parallax -->
<div data-swiper-parallax-scale="0.15">I will change scale</div>
</div>
...
</div>
</div>
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | 布尔值 | false | 启用,如果你想在滑块内使用“视差”元素 |
从版本 9 开始,Swiper 没有特定的延迟加载 API,因为它依赖于浏览器的原生延迟加载功能。要使用延迟加载,我们只需要在图像上设置 loading="lazy"
并添加预加载元素
<div class="swiper">
<div class="swiper-wrapper">
<!-- Lazy image -->
<div class="swiper-slide">
<img src="path/to/picture-1.jpg" loading="lazy" />
<div class="swiper-lazy-preloader"></div>
</div>
<!-- Lazy image with srcset -->
<div class="swiper-slide">
<img
src="path/to/logo-small.png"
srcset="path/to/logo-large.png 2x"
loading="lazy"
/>
<div class="swiper-lazy-preloader"></div>
</div>
</div>
</div>
如你所见
loading="lazy"
属性<div class="swiper-lazy-preloader"></div>
或为深色布局添加白色
<div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>
确保将 effect
参数设置为 'fade'
才能实现此效果。
crossFade
设置为 true
。名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
crossFade | 布尔值 | false | 启用幻灯片交叉淡入淡出 |
确保将 effect
参数设置为 'coverflow'
才能实现此效果。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
depth | 数字 | 100 | 以像素为单位的深度偏移(幻灯片在 Z 轴上平移) |
修饰符 | 数字 | 1 | 效果乘数 |
旋转 | 数字 | 50 | 滑动旋转度数 |
缩放 | 数字 | 1 | 滑动缩放效果 |
slideShadows | 布尔值 | true | 启用幻灯片阴影 |
拉伸 | 数字 | 0 | 拉伸幻灯片之间的间距(以 px 为单位) |
确保将 effect
参数设置为 'flip'
才能正常工作。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
limitRotation | 布尔值 | true | 限制边缘幻灯片的旋转 |
slideShadows | 布尔值 | true | 启用幻灯片阴影 |
确保将 effect
参数设置为 'cube'
才能正常工作。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
shadow | 布尔值 | true | 启用主滑块阴影 |
shadowOffset | 数字 | 20 | 以 px 为单位的主阴影偏移 |
shadowScale | 数字 | 0.94 | 主阴影缩放比例 |
slideShadows | 布尔值 | true | 启用幻灯片阴影 |
确保将 effect
参数设置为 'cards'
才能正常工作。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
perSlideOffset | 数字 | 8 | 每个幻灯片的偏移距离(以 px 为单位) |
perSlideRotate | 数字 | 2 | 每个幻灯片的旋转角度(以度为单位) |
旋转 | 布尔值 | true | 启用卡片旋转 |
slideShadows | 布尔值 | true | 启用幻灯片阴影 |
确保将 effect
参数设置为 'creative'
才能正常工作。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
limitProgress | 数字 | 1 | 将进度/偏移限制为侧边幻灯片数量。如果为 |
下一页 | CreativeEffectTransform | 下一张幻灯片变换。
| |
透视 | 布尔值 | true | 如果自定义变换需要 3D 变换( |
上一页 | CreativeEffectTransform | 上一张幻灯片变换。接受以下类型的对象
| |
进度倍数 | 数字 | 1 | 允许乘以幻灯片变换和不透明度。 |
每进度阴影 | 布尔值 | false | 根据 |
除了 控制器 组件,Swiper 还附带缩略图组件,该组件旨在与其他缩略图 swiper 协同工作,比用于同步两个 swiper 的控制器更正确。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
自动滚动偏移 | 数字 | 0 | 允许设置缩略图从边缘激活的幻灯片,它应该自动移动滚动缩略图。例如,如果设置为 1,最后一个可见缩略图将被激活(从边缘 1),它将自动滚动缩略图 |
多个活动缩略图 | 布尔值 | true | 启用后,可以激活多个缩略图幻灯片 |
幻灯片缩略图活动类 | 字符串 | 'swiper-slide-thumb-active' | 将添加到已激活的缩略图 swiper 幻灯片的附加类 |
swiper | 任意 | null | 用作缩略图的 swiper 的 Swiper 实例,或用于初始化缩略图 swiper 的具有 Swiper 参数的对象 |
缩略图容器类 | 字符串 | 'swiper-thumbs' | 将添加到缩略图 swiper 的附加类 |
属性 | ||
---|---|---|
swiper.swiper | 任意 | 缩略图 swiper 的 Swiper 实例 |
方法 | ||
swiper.init() | 初始化缩略图 | |
swiper.update(initial) | 更新缩略图 |
Swiper 支持缩放图像功能(类似于在浏览单张照片时在 iOS 上看到的功能),你可以通过捏合手势放大图像,或者通过双击图像放大/缩小。在这种情况下,需要额外的布局
<div class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide">
<div class="swiper-zoom-container">
<img src="path/to/image1.jpg" />
</div>
</div>
<div class="swiper-slide">
<div class="swiper-zoom-container">
<img src="path/to/image2.jpg" />
</div>
</div>
<div class="swiper-slide">Plain slide with text</div>
<div class="swiper-slide">
<!-- Override maxRatio parameter -->
<div class="swiper-zoom-container" data-swiper-zoom="5">
<img src="path/to/image1.jpg" />
</div>
</div>
</div>
</div>
swiper-zoom-container
类的 div 进行包装。img
、picture
或canvas
元素之一。如果你想对其他自定义元素进行缩放,只需向此元素添加swiper-zoom-target
类。例如
<div class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide">
<div class="swiper-zoom-container">
<!-- custom zoomable element -->
<div
class="swiper-zoom-target"
style="background-image: url(...)"
></div>
</div>
</div>
</div>
</div>
data-swiper-zoom
属性,为特定幻灯片覆盖maxRatio
参数。名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
containerClass | 字符串 | 'swiper-zoom-container' | 缩放容器的 CSS 类名 |
limitToOriginalSize | 布尔值 | false | 设置为 true 时,图像不会缩放超过其原始大小的 100% |
maxRatio | 数字 | 3 | 图像的最大缩放倍数 |
minRatio | 数字 | 1 | 图像的最小缩放倍数 |
toggle | 布尔值 | true | 通过幻灯片的双击启用/禁用放大 |
zoomedSlideClass | 字符串 | 'swiper-slide-zoomed' | 放大容器的 CSS 类名 |
属性 | ||
---|---|---|
swiper.enabled | 布尔值 | 缩放模块是否已启用 |
swiper.scale | 数字 | 当前图像缩放比例 |
方法 | ||
swiper.disable() | 禁用缩放模块 | |
swiper.enable() | 启用缩放模块 | |
swiper.in(ratio) | 放大当前活动幻灯片的图像。可选择接受自定义缩放比例 | |
swiper.out() | 缩小当前活动幻灯片的图像 | |
swiper.toggle(event) | 切换当前活动幻灯片的图像缩放 |
名称 | 参数 | 描述 |
---|---|---|
zoomChange | (swiper, scale, imageEl, slideEl) | 缩放更改时触发事件 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | 布尔值 | false | 设置为 |
onlyInViewport | 布尔值 | true | 启用后,它将控制当前在视口中的滑块 |
pageUpDown | 布尔值 | true | 启用后,它将通过 Page Up 和 Page Down 键启用键盘导航 |
属性 | ||
---|---|---|
swiper.enabled | 布尔值 | 是否启用键盘控制 |
方法 | ||
swiper.disable() | 禁用键盘控制 | |
swiper.enable() | 启用键盘控制 |
名称 | 参数 | 描述 |
---|---|---|
keyPress | (swiper, keyCode) | 按下键盘时触发事件 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | 布尔值 | false | 设置为 |
eventsTarget | 任意 | 'container' | 接受鼠标滚轮事件的容器的 CSS 选择器或 HTML 元素的字符串。默认情况下为 swiper |
forceToAxis | 布尔值 | false | 设置为 |
invert | 布尔值 | false | 设置为 |
noMousewheelClass | 字符串 | 'swiper-no-mousewheel' | 将忽略具有此类的元素上的滚动 |
releaseOnEdges | 布尔值 | false | 设置为 |
sensitivity | 数字 | 1 | 鼠标滚轮数据的乘数,允许调整鼠标滚轮灵敏度 |
thresholdDelta | null | 数字 | null | 触发 swiper 幻灯片更改的最小鼠标滚轮滚动增量 |
thresholdTime | null | 数字 | null | 触发 swiper 幻灯片更改的最小鼠标滚轮滚动时间增量(以毫秒为单位) |
属性 | ||
---|---|---|
swiper.enabled | 布尔值 | 是否启用鼠标滚轮控制 |
方法 | ||
swiper.disable() | 禁用鼠标滚轮控制 | |
swiper.enable() | 启用鼠标滚轮控制 |
名称 | 参数 | 描述 |
---|---|---|
scroll | (swiper, event) | 鼠标滚轮滚动时触发事件 |
虚拟幻灯片模块允许在 DOM 中仅保留所需数量的幻灯片。如果你有许多幻灯片,尤其是具有繁重的 DOM 树或图像的幻灯片,那么在性能和内存问题方面,它非常有用。
slidesPerView: 'auto'
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
addSlidesAfter | 数字 | 0 | 增加活动幻灯片后预渲染的幻灯片数量 |
addSlidesBefore | 数字 | 0 | 增加活动幻灯片前预渲染的幻灯片数量 |
cache | 布尔值 | true | 启用渲染幻灯片 HTML 元素的 DOM 缓存。一旦它们被渲染,它们将被保存到缓存中并从中重复使用。 |
enabled | 布尔值 | false | 是否启用虚拟幻灯片 |
renderExternal | function(data) | 用于外部渲染的函数(例如,使用其他一些库来处理 DOM 操作和状态,如 React.js 或 Vue.js)。它接受一个带有以下属性的
| |
renderExternalUpdate | 布尔值 | true | 当启用时(默认情况下),它将在调用 renderExternal 之后立即更新 Swiper 布局。当与异步渲染的渲染库一起使用时,禁用并手动更新 swiper 很有用 |
renderSlide | function(slide, index) | 用于渲染幻灯片的函数。它接受 | |
slides | T[] | [] | 包含幻灯片的数组 |
属性 | ||
---|---|---|
swiper.cache | 对象 | 包含缓存的幻灯片 HTML 元素的对象 |
swiper.from | 数字 | 第一个渲染幻灯片的索引 |
swiper.slides | T[] | 由 |
swiper.to | 数字 | 最后渲染幻灯片的索引 |
方法 | ||
swiper.appendSlide(slide) | 追加幻灯片。
| |
swiper.prependSlide(slide) | 前置幻灯片。
| |
swiper.removeAllSlides() | 移除所有幻灯片
| |
swiper.removeSlide(slideIndexes) | 移除特定幻灯片或幻灯片。
| |
swiper.update(force) | 更新虚拟幻灯片状态 |
从版本 9 开始,Swiper 虚拟幻灯片可以与最初在 DOM 中呈现的幻灯片一起使用。在初始化时,它会将它们从 DOM 中移除、缓存,然后重新使用所需的幻灯片
<div class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide">Slide 1</div>
<div class="swiper-slide">Slide 2</div>
...
<div class="swiper-slide">Slide 100</div>
</div>
</div>
<script>
const swiper = new Swiper('.swiper', {
virtual: {
enabled: true,
},
});
</script>
哈希导航旨在链接到特定幻灯片,以便加载打开特定幻灯片的页面。
要使其正常工作,您需要通过传递 hashNavigation:true
参数并添加 data-hash
属性中的幻灯片哈希来启用它
<div class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide" data-hash="slide1">Slide 1</div>
<div class="swiper-slide" data-hash="slide2">Slide 2</div>
<div class="swiper-slide" data-hash="slide3">Slide 3</div>
<div class="swiper-slide" data-hash="slide4">Slide 4</div>
<div class="swiper-slide" data-hash="slide5">Slide 5</div>
...
</div>
</div>
const swiper = new Swiper('.swiper', {
//enable hash navigation
hashNavigation: true,
});
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
getSlideIndex | function(swiper, hash) | 旨在与虚拟幻灯片一起使用,当无法通过哈希在 DOM 中找到幻灯片时(例如尚未呈现) | |
replaceState | 布尔值 | false | 除了 hashnav 之外,还用于将当前 URL 状态替换为新状态,而不是将其添加到历史记录中 |
watchState | 布尔值 | false | 设置为 |
名称 | 参数 | 描述 |
---|---|---|
hashChange | (swiper) | 窗口哈希值更改时触发事件 |
hashSet | (swiper) | Swiper 更新哈希值时触发事件 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | 布尔值 | false | 启用历史插件。 |
keepQuery | 布尔值 | false | 更改浏览器 URL 时保留查询参数。 |
key | 字符串 | 'slides' | 幻灯片的 URL 键 |
replaceState | 布尔值 | false | 除了 hashnav 或历史记录外,还可以替换当前 URL 状态,而不是将其添加到历史记录中 |
root | 字符串 | '' | Swiper 页面根目录,当您在非根网站页面上使用 Swiper 历史模式时指定此项非常有用。例如,可以是 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
by | 'slide' | 'container' | “滑动” | 定义控制另一个滑块的方式:逐个幻灯片(相对于其他滑块的网格)或根据所有幻灯片/容器(取决于总滑块百分比)。 |
control | 任意 | 在此处传递另一个 Swiper 实例或包含应由该 Swiper 控制的 Swiper 实例的数组。还接受带有 Swiper 元素 CSS 选择器的字符串或 Swiper 元素的 HTMLElement | |
inverse | 布尔值 | false | 设置为 |
属性 | ||
---|---|---|
swiper.control | 任意 | 在此处传递另一个 Swiper 实例或包含应由该 Swiper 控制的 Swiper 实例的数组 |
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
containerMessage | null | 字符串 | null | 屏幕阅读器用于外部 swiper 容器的消息 |
containerRoleDescriptionMessage | null | 字符串 | null | 用于屏幕阅读器描述外部 swiper 容器角色的消息 |
enabled | 布尔值 | true | 启用 A11y |
firstSlideMessage | 字符串 | “这是第一张幻灯片” | 当 swiper 处于第一张幻灯片时,用于屏幕阅读器上一个按钮的消息 |
id | null | string | number | null | 要设置在 swiper-wrapper 上的 |
itemRoleDescriptionMessage | null | 字符串 | null | 用于屏幕阅读器描述幻灯片元素角色的消息 |
lastSlideMessage | 字符串 | “这是最后一张幻灯片” | 当 swiper 处于最后一张幻灯片时,用于屏幕阅读器下一个按钮的消息 |
nextSlideMessage | 字符串 | “下一张幻灯片” | 用于屏幕阅读器上一个按钮的消息 |
notificationClass | 字符串 | “swiper-notification” | A11y 通知的 CSS 类名 |
paginationBulletMessage | 字符串 | “转到幻灯片 {{index}}” | 用于屏幕阅读器描述单个分页项目的消息 |
prevSlideMessage | 字符串 | “上一张幻灯片” | 用于屏幕阅读器上一个按钮的消息 |
slideLabelMessage | 字符串 | “{{index}} / {{slidesLength}}” | 用于屏幕阅读器描述幻灯片元素标签的消息 |
slideRole | 字符串 | “group” | swiper 幻灯片 |
你有两个选项可以制作自定义版本的 Swiper。
如果你在你的项目中使用支持 JS 模块的打包器,你可以只导入你需要的模块
// Import Swiper and modules
import Swiper from 'swiper';
import { Navigation, Pagination, Scrollbar } from 'swiper/modules';
// Now you can use Swiper
const swiper = new Swiper('.swiper', {
// Install modules
modules: [Navigation, Pagination, Scrollbar],
speed: 500,
navigation: {
nextEl: '.swiper-button-next',
prevEl: '.swiper-button-prev',
},
// ...
});
导出的模块如下
Virtual
- 虚拟幻灯片模块Keyboard
- 键盘控制模块Mousewheel
- 鼠标滚轮控制模块Navigation
- 导航模块Pagination
- 分页模块Scrollbar
- 滚动条模块Parallax
- 视差模块FreeMode
- 自由模式模块Grid
- 网格模块Manipulation
- 幻灯片操作模块(仅适用于核心版本)Zoom
- 缩放模块Controller
- 控制器模块A11y
- 无障碍模块History
- 历史导航模块HashNavigation
- 哈希导航模块Autoplay
- 自动播放模块EffectFade
- 淡入淡出效果模块EffectCube
- 立方体效果模块EffectFlip
- 翻转效果模块EffectCoverflow
- 视差效果模块EffectCards
- 卡片效果模块EffectCreative
- 创意效果模块Thumbs
- 缩略图模块Swiper 附带 gulp 构建器,允许构建自定义库版本,其中你只能包含必需的模块。我们需要以下内容
下载并解压 Swiper GitHub 存储库 到本地文件夹
安装 Node.js(如果未安装)
现在,我们需要安装必需的依赖项。转到下载并解压的 Swiper 存储库文件夹,并在终端中执行
$ npm install
打开 scripts/build-config.js
文件
module.exports = {
// remove modules you don't need
modules: [
'virtual',
'keyboard',
'mousewheel',
'navigation',
'pagination',
'scrollbar',
'parallax',
'zoom',
'controller',
'a11y',
'history',
'hash-navigation',
'autoplay',
'thumbs',
'free-mode',
'grid',
'manipulation',
'effect-fade',
'effect-cube',
'effect-flip',
'effect-coverflow',
'effect-creative',
'effect-cards',
],
};
现在,我们准备构建 Swiper 的自定义版本
$ npm run build:prod
就是这样。生成的 CSS 和 JS 文件及其缩小版本将在 dist/
文件夹中提供。
Swiper 完全类型化,它导出 Swiper
和 SwiperOptions
类型
// main.ts
import Swiper from 'swiper';
import { SwiperOptions } from 'swiper/types';
const swiperParams: SwiperOptions = {
slidesPerView: 3,
spaceBetween: 50,
};
const swiper = new Swiper('.swiper', swiperParams);
你还可以查看自动生成的 TypeScript 定义浏览器 以了解所有类型、选项、属性和方法。