Swiper API

如果您要从 Swiper 9 升级到 Swiper 10,请查看Swiper 10 迁移指南

Swiper 完整 HTML 布局

<!-- 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 样式

捆绑版本 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 样式

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 样式

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

现在,当我们有 Swiper 的 HTML 时,我们需要使用以下函数对其进行初始化

new Swiper(swiperContainer, parameters)- 使用选项初始化 swiper

  • swiperContainer - swiper 容器 HTML 元素的 HTMLElement 或字符串(带 CSS 选择器)。必需。
  • parameters - 对象 - 带有 Swiper 参数的对象。可选。
  • 方法返回已初始化的 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 参数的对象或布尔值 true 以启用默认设置。

const swiper = new Swiper('.swiper', {
  a11y: {
    prevSlideMessage: 'Previous slide',
    nextSlideMessage: 'Next slide',
  },
});
allowSlideNext布尔值true

设置为 false 以禁用向下一张幻灯片方向(向右或向下)滑动

allowSlidePrev布尔值true

设置为 false 以禁用向上一张幻灯片方向(向左或向上)滑动

allowTouchMove布尔值true

如果为 false,则切换幻灯片的唯一方法是使用外部 API 函数,如 slidePrev 或 slideNext

autoHeight布尔值false

设置为 true,滑块包装器将根据当前活动幻灯片的高度调整其高度

autoplay任意

带有自动播放参数的对象或布尔值 true 以启用默认设置

const swiper = new Swiper('.swiper', {
 autoplay: {
   delay: 5000,
 },
});
breakpoints对象

允许为不同的响应断点(屏幕大小)设置不同的参数。并非所有参数都可以在断点中更改,只有那些不需要不同布局和逻辑的参数,如 slidesPerViewslidesPerGroupspaceBetweengrid.rows。诸如 loopeffect 之类的参数将不起作用

const swiper = new Swiper('.swiper', {
  // Default parameters
  slidesPerView: 1,
  spaceBetween: 10,
  // Responsive breakpoints
  breakpoints: {
    // when window width is >= 320px
    320: {
      slidesPerView: 2,
      spaceBetween: 20
    },
    // when window width is >= 480px
    480: {
      slidesPerView: 3,
      spaceBetween: 30
    },
    // when window width is >= 640px
    640: {
      slidesPerView: 4,
      spaceBetween: 40
    }
  }
})
const swiper = new Swiper('.swiper', {
  slidesPerView: 1,
  spaceBetween: 10,
  // using "ratio" endpoints
  breakpoints: {
    '@0.75': {
      slidesPerView: 2,
      spaceBetween: 20,
    },
    '@1.00': {
      slidesPerView: 3,
      spaceBetween: 40,
    },
    '@1.50': {
      slidesPerView: 4,
      spaceBetween: 50,
    },
  }
});
breakpointsBase'container' | 'window''window'

断点的基准(测试版)。可以是 windowcontainer。如果设置为 window(默认),则断点键表示窗口宽度。如果设置为 container,则断点键将视为 swiper 容器宽度

cardsEffect任意

带有卡片效果参数的对象

const swiper = new Swiper('.swiper', {
  effect: 'cards',
  cardsEffect: {
    // ...
  },
});
centerInsufficientSlides布尔值false

启用后,如果幻灯片数量少于 slidesPerView,则幻灯片居中。不打算使用 loop 模式和 grid.rows

centeredSlides布尔值false

如果为 true,则活动幻灯片将居中,而不仅仅在左侧。

centeredSlidesBounds布尔值false

如果为 true,则活动幻灯片将居中,而不会在滑块的开头和结尾添加间隙。需要 centeredSlides: true。不打算与 looppagination 一起使用

containerModifierClass字符串'swiper-'

根据不同的参数可以添加到 swiper 容器的修改器 CSS 类的开头

controller任意

带有控制器参数的对象或布尔值 true,以启用默认设置

const swiper = new Swiper('.swiper', {
  controller: {
    inverse: true,
  },
});
coverflowEffect任意

带有 Coverflow 效果参数的对象。

const swiper = new Swiper('.swiper', {
  effect: 'coverflow',
  coverflowEffect: {
    rotate: 30,
    slideShadows: false,
  },
});
createElements布尔值false

启用后,Swiper 将自动使用 swiper-wrapper 元素包装幻灯片,并将为导航、分页和滚动条创建所需的元素(使用它们各自的参数对象或布尔值 true))

creativeEffect任意

带有创意效果参数的对象

const swiper = new Swiper('.swiper', {
  effect: 'creative',
  creativeEffect: {
    prev: {
      // will set `translateZ(-400px)` on previous slides
      translate: [0, 0, -400],
    },
    next: {
      // will set `translateX(100%)` on next slides
      translate: ['100%', 0, 0],
    },
  },
});
cssMode布尔值false

启用后,它将使用现代 CSS Scroll Snap API。它不支持 Swiper 的所有功能,但可能在简单配置中带来更好的性能。

启用后,不支持以下内容

  • Cube 效果
  • speed 参数可能没有效果
  • 所有过渡开始/结束相关事件(改用 slideChange
  • slidesPerGroup 支持有限
  • simulateTouch 没有效果,并且无法用鼠标“拖动”
  • resistance 没有效果
  • allowSlidePrev/Next
  • swipeHandler

如果你将它与其他效果(尤其是 3D 效果)一起使用,则需要使用 <div className="swiper-slide-transform"> 元素包装幻灯片的内容。如果你在幻灯片上使用任何自定义样式(如背景颜色、边框半径、边框等),则应将其设置在 swiper-slide-transform 元素上。

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <!-- wrap slide content with transform element -->
      <div class="swiper-slide-transform">
        ... slide content ...
      </div>
    </div>
    ...
  </div>
</div>
<script>
const swiper = new Swiper('.swiper', {
   effect: 'flip',
   cssMode: true,
 });
</script>
cubeEffect任意

带有 Cube 效果参数的对象

const swiper = new Swiper('.swiper', {
  effect: 'cube',
  cubeEffect: {
    slideShadows: false,
  },
});
direction'horizontal' | 'vertical'“水平”

可以是 “水平”“垂直”(适用于垂直滑块)。

edgeSwipeDetection字符串 | 布尔值false

启用以释放 Swiper 事件,以便在应用中进行轻扫返回操作。如果设置为 “阻止”,则它将阻止系统轻扫返回导航。此功能仅适用于“触摸”事件(而不是指针事件),因此它适用于 iOS/Android 设备,而不适用于具有指针(触摸)事件的 Windows 设备。

edgeSwipeThreshold数字20

从屏幕左侧开始的区域(以像素为单位),用于释放触摸事件以在应用中进行轻扫返回操作

effect字符串“滑动”

过渡效果。可以是 “滑动”“淡入淡出”“立方体”“封面流”“翻转”“创意”“卡片”

enabled布尔值true

Swiper 是否最初已启用。当 Swiper 被禁用时,它将隐藏所有导航元素,并且不会对任何事件和交互做出响应

eventsPrefix字符串`swiper`

Swiper Element(网络组件)发出的所有 DOM 事件的事件名称前缀

fadeEffect任意

具有淡入淡出效果参数的对象

const swiper = new Swiper('.swiper', {
  effect: 'fade',
  fadeEffect: {
    crossFade: true
  },
});
flipEffect任意

具有翻转效果参数的对象

const swiper = new Swiper('.swiper', {
  effect: 'flip',
  flipEffect: {
    slideShadows: false,
  },
});
focusableElements字符串“input、select、option、textarea、button、video、label”

可聚焦元素的 CSS 选择器。如果此类元素“被聚焦”,则将禁用轻扫操作

followFinger布尔值true

如果禁用,则仅在释放滑块时才会对其进行动画处理,当手指按住滑块时,它不会移动

freeMode任意

启用自由模式功能。具有自由模式参数的对象或布尔值 true,以使用默认设置启用。

const swiper = new Swiper('.swiper', {
  freeMode: true,
});

const swiper = new Swiper('.swiper', {
  freeMode: {
    enabled: true,
    sticky: true,
  },
});
grabCursor布尔值false

此选项可能会稍微提高桌面可用性。如果为 true,则用户在将鼠标悬停在 Swiper 上时将看到“抓取”光标

grid任意

具有网格参数的对象,用于启用“多行”滑块。

const swiper = new Swiper('.swiper', {
  grid: {
    rows: 2,
  },
});
hashNavigation任意

启用哈希 URL 导航以用于幻灯片。具有哈希导航参数的对象或布尔值 true,以使用默认设置启用

const swiper = new Swiper('.swiper', {
  hashNavigation: {
    replaceState: true,
  },
});
heightnull | 数字null

Swiper 高度(以像素为单位)。此参数允许强制设置 Swiper 高度。仅当在隐藏时初始化 Swiper 以及在 SSR 和测试环境中进行正确的 Swiper 初始化时才有用

设置此参数将使 Swiper 失去响应性

history任意

启用历史记录推送状态,其中每张幻灯片都有自己的 URL。在此参数中,您必须指定主幻灯片 URL,如 "slides",并使用 data-history 属性指定每张幻灯片的 URL。

具有历史记录导航参数的对象或布尔值 true,以启用默认设置

const swiper = new Swiper('.swiper', {
  history: {
    replaceState: true,
  },
});
<!-- will produce "slides/slide1" url in browser history -->
<div class="swiper-slide" data-history="slide1"></div>
init布尔值true

当您创建实例时,是否应自动初始化 Swiper。如果禁用,则需要通过调用 swiper.init() 手动初始化它

initialSlide数字0

初始幻灯片的索引号。

injectStylesstring[]

将文本样式注入到 Shadow DOM 中。仅适用于 Swiper Element

injectStylesUrlsstring[]

将样式 <link>s 注入到 Shadow DOM 中。仅适用于 Swiper Element

keyboard任意

启用通过键盘导航幻灯片。具有键盘参数的对象或布尔值 true,以启用默认设置

const swiper = new Swiper('.swiper', {
  keyboard: {
    enabled: true,
    onlyInViewport: false,
  },
});
lazyPreloadPrevNext数字0

要预加载的下一张和上一张幻灯片数量。仅适用于使用延迟加载时。

lazyPreloaderClass字符串'swiper-lazy-preloader'

延迟预加载器的 CSS 类名

longSwipes布尔值true

如果要禁用长滑动,请设置为 false

longSwipesMs数字300

在长滑动期间触发滑动到下一张/上一张幻灯片的最小持续时间(以毫秒为单位)

longSwipesRatio数字0.5

在长滑动期间触发滑动到下一张/上一张幻灯片的比率

loop布尔值false

设置为 true 以启用连续循环模式

由于循环模式的工作原理(它将重新排列幻灯片),幻灯片的总数必须

  • 大于或等于 slidesPerView + slidesPerGroup
  • 甚至 slidesPerGroup(或使用 loopAddBlankSlides 参数)
  • 甚至 grid.rows(或使用 loopAddBlankSlides 参数)
loopAddBlankSlides布尔值true

如果您使用 Grid 或 slidesPerGroup,并且幻灯片的总数不是 slidesPerGroupgrid.rows 的偶数,则自动添加空白幻灯片

loopAdditionalSlides数字0

允许增加循环幻灯片数量

loopPreventsSliding布尔值true

如果启用,则在循环模式下滑块动画播放时,slideNext/Prev 将不起作用

maxBackfaceHiddenSlides数字10

如果幻灯片的总数少于此处指定的值,则 Swiper 将在幻灯片元素上启用 backface-visibility: hidden 以减少 Safari 中的视觉“闪烁”。

不建议在大量幻灯片上启用它,因为它会降低性能

模块any[]

带有 Swiper 模块的数组

import Swiper from 'swiper';
import { Navigation, Pagination } from 'swiper/modules';

const swiper = new Swiper('.swiper', {
   modules: [ Navigation, Pagination ],
 });
mousewheel任意

使用鼠标滚轮浏览幻灯片。带有鼠标滚轮参数的对象或布尔值 true,以使用默认设置启用

const swiper = new Swiper('.swiper', {
  mousewheel: {
    invert: true,
  },
});
navigation任意

带有导航参数的对象或布尔值 true,以使用默认设置启用。

const swiper = new Swiper('.swiper', {
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
});
nested布尔值false

在 Swiper 上设置为 true,以正确拦截触摸事件。仅在与父级使用相同方向的滑块上使用

noSwiping布尔值true

在与 noSwipingClass 中指定类匹配的元素上启用/禁用滑动

noSwipingClass字符串'swiper-no-swiping'

指定 noSwiping 的元素 css 类

noSwipingSelector字符串

可用于代替 noSwipingClass 来指定禁用滑动的元素。例如,'input' 将禁用所有输入的滑动

normalizeSlideIndex布尔值true

标准化幻灯片索引。

observeParents布尔值false

如果您还需要监视 Swiper 父元素的变动,则设置为 true

observeSlideChildren布尔值false

如果您还需要监视 Swiper 幻灯片子元素的变动,则设置为 true

observer布尔值false

设置为 true 以在 Swiper 及其元素上启用变动观察器。在这种情况下,如果您更改其样式(如隐藏/显示)或修改其子元素(如添加/移除幻灯片),Swiper 将每次更新(重新初始化)

on对象

注册事件处理程序

onAnyfunction(handler)

添加将在所有事件上触发的事件侦听器

const swiper = new Swiper('.swiper', {
   onAny(eventName, ...args) {
     console.log('Event: ', eventName);
     console.log('Event data: ', args);
   }
 });
oneWayMovement布尔值false

启用后,无论滑动方向如何,都只会向前滑动幻灯片(单向)

pagination任意

带有分页参数的对象或布尔值 true,以使用默认设置启用。

const swiper = new Swiper('.swiper', {
  pagination: {
    el: '.swiper-pagination',
    type: 'bullets',
  },
});
parallax任意

带有视差参数的对象或布尔值 true,以使用默认设置启用。

const swiper = new Swiper('.swiper', {
  parallax: true,
});
passiveListeners布尔值true

在可能的情况下,默认情况下将使用被动事件侦听器来提高移动设备上的滚动性能。但是,如果您需要使用 e.preventDefault 并且与之发生冲突,则应禁用此参数

preventClicks布尔值true

设置为 true 以防止在滑动期间意外点击链接

preventClicksPropagation布尔值true

在滑动期间将点击事件传播到链接上设置为true

preventInteractionOnTransition布尔值false

启用后,在过渡期间不允许通过滑动或导航/分页按钮更改幻灯片

resistance布尔值true

如果您想禁用抗性边界,请将其设置为false

resistanceRatio数字0.85

此选项允许您控制抗性比率

resizeObserver布尔值true

启用后,它将在 swiper 容器上使用 ResizeObserver(如果浏览器支持)来检测容器大小调整(而不是监视窗口大小调整)

rewind布尔值false

设置为true以启用“倒带”模式。启用后,在最后一页上单击“下一步”导航按钮(或调用.slideNext())将滑回到第一页。在第一页上单击“上一步”导航按钮(或调用.slidePrev())将向前滑动到最后一页。

不应与loop模式一起使用

roundLengths布尔值false

设置为true以将幻灯片宽度和高度的值四舍五入,以防止在通常分辨率的屏幕上出现模糊文本(如果您有此类文本)

runCallbacksOnInit布尔值true

在 swiper 初始化时触发过渡/幻灯片更改/开始/结束事件。如果您的 initialSlide 不为 0,或者您使用循环模式,则会在初始化时触发此类事件

scrollbar任意

带滚动条参数的对象或布尔值true以启用默认设置。

const swiper = new Swiper('.swiper', {
  scrollbar: {
    el: '.swiper-scrollbar',
    draggable: true,
  },
});
setWrapperSize布尔值false

启用此选项,插件将在 swiper wrapper 上设置宽度/高度,等于所有幻灯片的总大小。主要用作兼容性后备选项,适用于不支持 flexbox 布局的浏览器

shortSwipes布尔值true

如果您想禁用短滑动,请将其设置为false

simulateTouch布尔值true

如果为true,Swiper 将接受鼠标事件,例如触摸事件(单击并拖动以更改幻灯片)

slideActiveClass字符串'swiper-slide-active'

当前活动幻灯片的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 组件中不受支持

slideBlankClass字符串'swiper-slide-blank'

循环模式添加的空白幻灯片的 CSS 类名(当启用loopAddBlankSlides时)

在 Swiper React/Vue 中不受支持

slideClass字符串'swiper-slide'

幻灯片的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 组件中不受支持

slideFullyVisibleClass字符串'swiper-slide-fully-visible'

完全(当整个幻灯片在视口中)可见幻灯片的 CSS 类名

在 Swiper React/Vue 中不受支持

slideNextClass字符串'swiper-slide-next'

紧随当前活动幻灯片之后的幻灯片的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 中不受支持

slidePrevClass字符串'swiper-slide-prev'

紧靠当前活动幻灯片之前的幻灯片的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 中不受支持

slideToClickedSlide布尔值false

设置为 true,单击任何幻灯片都将产生过渡到此幻灯片

slideVisibleClass字符串'swiper-slide-visible'

当前/部分可见幻灯片的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 中不受支持

slidesOffsetAfter数字0

在容器末尾(所有幻灯片之后)添加(以像素为单位)附加幻灯片偏移量

slidesOffsetBefore数字0

在容器开头(所有幻灯片之前)添加(以像素为单位)附加幻灯片偏移量

slidesPerGroup数字1

设置幻灯片数量以定义和启用组滑动。与 slidesPerView > 1 一起使用很有用

slidesPerGroupAuto布尔值false

此参数仅用于 slidesPerView: 'auto'slidesPerGroup: 1。启用后,它将在 .slideNext().slidePrev() 方法调用、导航“按钮”单击和自动播放时跳过视图中的所有幻灯片。

slidesPerGroupSkip数字0

该参数的工作方式如下:如果 slidesPerGroupSkip 等于 0(默认值),则没有幻灯片被排除在分组之外,并且产生的行为与没有此更改时的行为相同。

如果 slidesPerGroupSkip 等于或大于 1,则前 X 个幻灯片被视为单个组,而所有后续幻灯片则按 slidesPerGroup 值分组。

slidesPerViewnumber | 'auto'1

每个视图的幻灯片数量(在滑块容器上同时可见的幻灯片)。

grid.rows > 1 时,slidesPerView: 'auto' 当前与多行模式不兼容

spaceBetweenstring | number0

幻灯片之间的距离(以像素为单位)。

如果您对传入“spaceBetween”的 Swiper 中的元素使用“margin”css 属性,则导航可能无法正常工作。

speed数字300

幻灯片之间过渡的持续时间(以毫秒为单位)

swipeHandler任意null

带有分页容器的 CSS 选择器或 HTML 元素的字符串,该容器将作为仅可用于滑动的可用处理程序

swiperElementNodeName字符串'SWIPER-CONTAINER'

swiper 元素节点名称的名称;用于检测 Web 组件渲染

阈值数字5

以 px 为单位的阈值。如果“触摸距离”低于此值,则 swiper 将不会移动

缩略图任意

包含缩略图组件参数的对象

const swiper = new Swiper('.swiper', {
  ...
  thumbs: {
    swiper: thumbsSwiper
  }
});
触摸角度数字45

触发触摸移动的允许角度(以度为单位)

触摸事件目标'container' | 'wrapper''wrapper'

侦听触摸事件的目标元素。可以是 'container'(在 swiper 上侦听触摸事件)或 'wrapper'(在 swiper-wrapper 上侦听触摸事件)

触摸移动阻止传播布尔值false

如果启用,则将停止“touchmove”的传播

触摸比率数字1

触摸比率

边缘触摸释放布尔值false

启用此功能可在滑块边缘位置(开始、结束)释放触摸事件,以便进一步滚动页面。此功能仅适用于“触摸”事件(而不是指针事件),因此它适用于 iOS/Android 设备,但不适用于具有指针事件的 Windows 设备。此外,threshold 参数必须设置为 0

触摸开始强制阻止默认布尔值false

强制始终阻止 touchstartpointerdown)事件的默认行为

触摸开始阻止默认布尔值true

如果禁用,则不会阻止 pointerdown 事件

唯一的导航元素布尔值true

如果启用(默认情况下)并且导航元素的参数作为字符串传递(如 ".pagination"),则 Swiper 将首先通过子元素查找此类元素。适用于分页、上一个/下一个按钮和滚动条元素

窗口调整大小时更新布尔值true

Swiper 将在窗口调整大小时(方向更改)重新计算幻灯片位置

网址null | 字符串null

当在服务器端渲染并启用历史记录时,需要此功能来检测活动幻灯片

用户代理null | 字符串null

用户代理字符串。在服务器端渲染时,需要此功能来检测浏览器/设备

虚拟任意

启用虚拟幻灯片功能。包含虚拟幻灯片参数的对象或布尔值 true,以启用默认设置。

const swiper = new Swiper('.swiper', {
  virtual: {
    slides: ['Slide 1', 'Slide 2', 'Slide 3', 'Slide 4', 'Slide 5'],
  },
});
虚拟翻译布尔值false

启用此选项,swiper 将像往常一样操作,但它不会移动,包装器上的真实平移值不会被设置。当您可能需要创建自定义幻灯片过渡时,此功能非常有用

观察溢出布尔值true

启用此功能后,如果幻灯片不足以滑动,则 Swiper 将被禁用并隐藏导航按钮。

观察幻灯片进度布尔值false

启用此功能可计算每个幻灯片的进度和可见性(视口中的幻灯片将具有额外的可见类)

宽度null | 数字null

Swiper 宽度(以像素为单位)。此参数允许强制设置 Swiper 宽度。仅在 Swiper 在隐藏状态下初始化时,以及在 SSR 和测试环境中,为正确初始化 Swiper 时才很有用

设置此参数将使 Swiper 失去响应性

wrapperClass字符串'swiper-wrapper'

幻灯片包装器的 CSS 类名

通过更改类,您还需要更改 Swiper 的 CSS 以反映更改的类

在 Swiper React/Vue 中不受支持

zoom任意

启用缩放功能。包含缩放参数的对象或布尔值 true,以使用默认设置启用

const swiper = new Swiper('.swiper', {
  zoom: {
    maxRatio: 5,
  },
});

方法和属性

在初始化 Slider 后,我们会在变量中获得其已初始化的实例(如上例中的 swiper 变量),其中包含有用的方法和属性

属性
swiper.a11y任意
swiper.activeIndex数字

当前活动幻灯片的索引号

请注意,在循环模式下,活动索引值将始终在循环幻灯片数量上发生偏移

swiper.allowSlideNext布尔值

通过将 false / true 分配给此属性,禁用/启用滑动到下一张幻灯片的能力

swiper.allowSlidePrev布尔值

通过将 false / true 分配给此属性,禁用/启用滑动到上一张幻灯片的能力

swiper.allowTouchMove布尔值

通过将 false / true 分配给此属性,禁用/启用通过用鼠标抓取或用手指触摸(在触摸屏上)来移动滑块的能力

swiper.animating布尔值

如果 swiper 正在过渡,则为 true

swiper.autoplay任意
swiper.cardsEffect任意
swiper.clickedIndex数字

上次单击的幻灯片的索引号

swiper.clickedSlideHTMLElement

指向上次单击的幻灯片(HTMLElement)的链接

swiper.controller任意
swiper.coverflowEffect任意
swiper.creativeEffect任意
swiper.cubeEffect任意
swiper.defaults任意

Swiper 默认选项

swiper.elHTMLElement

Slider 容器 HTML 元素

swiper.extendedDefaults任意

包含全局 Swiper 扩展选项的对象

swiper.fadeEffect任意
swiper.flipEffect任意
swiper.freeMode任意
swiper.hashNavigation任意
swiper.height数字

容器高度

swiper.history任意
swiper.isBeginning布尔值

如果滑块处于最“左”/“上”位置,则为 true

swiper.isEnd布尔值

如果滑块处于最“右”/“下”位置,则为 true

swiper.isLocked布尔值

如果幻灯片被“锁定”(通过 watchOverflow),并且幻灯片不能被,例如,当幻灯片数量少于每视图的幻灯片时,则为 true

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.slidesHTMLElement[]

幻灯片 HTML 元素的数组。要获取特定的幻灯片 HTMLElement,请使用 swiper.slides[1]

swiper.snapGridnumber[]

幻灯片捕捉网格

swiper.snapIndex数字

snapGrid 中当前捕捉的索引号

swiper.swipeDirection'prev' | 'next'

滑动方向

swiper.thumbs任意
swiper.touches对象

包含以下触摸事件属性的对象

  • swiper.touches.startX
  • swiper.touches.startY
  • swiper.touches.currentX
  • swiper.touches.currentY
  • swiper.touches.diff
swiper.translate数字

包装器平移的当前值

swiper.virtual任意
swiper.width数字

容器的宽度

swiper.wrapperElHTMLElement

包装器 HTML 元素

swiper.zoom任意
方法
swiper.attachEvents()

再次附加所有事件侦听器

swiper.changeDirection(direction, needUpdate)

将滑块方向从水平更改为垂直,反之亦然。

  • direction - 'horizontal' | 'vertical' - 新方向。如果未指定,则会自动更改为相反方向
  • needUpdate - boolean - 将调用 swiper.update()。默认值为 true
swiper.changeLanguageDirection(direction)

更改滑块语言

  • direction - 'rtl' | 'ltr' - 新方向。应该是 `rtl` 或 `ltr`
swiper.destroy(deleteInstance, cleanStyles)

销毁滑块实例并分离所有事件侦听器

  • deleteInstance - 布尔值 - 将其设置为 false(默认值为 true)以不删除 Swiper 实例
  • cleanStyles - 布尔值 - 将其设置为 true(默认值为 true),所有自定义样式都将从幻灯片、包装器和容器中删除。如果你需要销毁 Swiper 并使用新选项或不同方向重新初始化,则很有用
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 平移进度(从 0 到 1)。
  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
swiper.setTranslate(平移)

为 swiper 包装器设置自定义 css3 转换的平移值

swiper.slideNext(速度, 运行回调)

运行过渡到下一张幻灯片。

  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slidePrev(speed, runCallbacks)

运行过渡到上一张幻灯片。

  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slideReset(speed, runCallbacks)

将 swiper 位置重置为当前活动幻灯片,持续时间等于“speed”参数。

  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slideTo(index, speed, runCallbacks)

运行过渡到幻灯片,其索引号等于“index”参数,持续时间等于“speed”参数。

  • index - number - 幻灯片的索引号。
  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slideToClosest(speed, runCallbacks)

将 swiper 位置重置为最接近的幻灯片/捕捉点,持续时间等于“speed”参数。

  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slideToLoop(index, speed, runCallbacks)

与 .slideTo 相同,但用于启用循环的情况。因此,此方法将滑动到 realIndex 与传递的索引匹配的幻灯片

  • index - number - 幻灯片的索引号。
  • 速度 - 数字 - 过渡持续时间(以毫秒为单位)。
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件。
swiper.slidesPerViewDynamic()

获取按视图动态计算的幻灯片数量,仅当 slidesPerView 设置为 auto 时才有效

swiper.translateTo(translate, speed, runCallbacks, translateBounds)

为 swiper 包装器设置自定义 css3 transform 的 translate 值

  • translate - number - 转换值(以像素为单位)
  • speed - number - 过渡持续时间(以毫秒为单位)
  • runCallbacks - boolean - 将其设置为 false(默认情况下为 true),过渡将不会产生过渡事件
  • translateBounds - boolean - 将其设置为 false(默认情况下为 true),过渡值可以超出最小和最大转换
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 带有一堆有用的事件,您可以监听。可以通过两种方式分配事件

  1. 在 swiper 初始化时使用 on 参数

    const swiper = new Swiper('.swiper', {
      // ...
      on: {
        init: function () {
          console.log('swiper initialized');
        },
      },
    });
    
  2. 在 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 时触发事件。接收 pointerup 事件作为参数。

destroy(swiper)

在 swiper 销毁时触发事件

doubleClick(swiper, event)

当用户在 Swiper 上双击/轻触时触发事件

doubleTap(swiper, event)

当用户双击 Swiper 的容器时触发事件。接收 pointerup 事件作为参数

fromEdge(swiper)

当 Swiper 从开始或结束位置移动时触发事件

init(swiper)

Swiper 初始化后立即触发。

请注意,使用 swiper.on('init') 语法时,只有在设置 init: false 参数时才会起作用。

const swiper = new Swiper('.swiper', {
  init: false,
  // other parameters
});
swiper.on('init', function() {
 // do something
});
// init Swiper
swiper.init();
// Otherwise use it as the parameter:
const swiper = new Swiper('.swiper', {
  // other parameters
  on: {
    init: function () {
      // do something
    },
  }
});
lock(swiper)

当 swiper 被锁定时(当启用 watchOverflow 时)触发事件

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 上移动并移动它时触发事件。接收 pointermove 事件作为参数。

slidesGridLengthChange(swiper)

幻灯片网格更改时触发事件

slidesLengthChange(swiper)

幻灯片数量更改时触发事件

slidesUpdated(swiper)

幻灯片及其大小计算并更新后触发事件

snapGridLengthChange(swiper)

捕捉网格更改时触发事件

snapIndexChange(swiper)

捕捉索引更改时触发事件

轻触(swiper, event)

当用户点击/轻触 Swiper 时触发事件。接收 pointerup 事件作为参数。

toEdge(swiper)

当 Swiper 滑动至起始或结束位置时触发事件

touchEnd(swiper, event)

当用户释放 Swiper 时触发事件。接收 pointerup 事件作为参数。

touchMove(swiper, event)

当用户触碰并滑动手指操作 Swiper 时触发事件。接收 pointermove 事件作为参数。

touchMoveOpposite(swiper, event)

当用户触碰并滑动手指操作 Swiper 时触发事件,且滑动方向与 direction 参数相反。接收 pointermove 事件作为参数。

touchStart(swiper, event)

当用户触碰 Swiper 时触发事件。接收 pointerdown 事件作为参数。

transitionEnd(swiper)

过渡结束后触发事件。

transitionStart(swiper)

过渡开始时触发事件。

unlock(swiper)

当 swiper 解锁时触发事件(当启用 watchOverflow 时)

update(swiper)

调用 swiper.update() 后触发事件

模块

名称类型默认值描述
disabledClass字符串'swiper-button-disabled'

当导航按钮变为禁用状态时添加的 CSS 类名

enabled布尔值

与断点一起使用的布尔属性,用于在特定断点上启用/禁用导航

hiddenClass字符串'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.nextElHTMLElement

“下一步”导航按钮的 HTMLElement

swiper.prevElHTMLElement

“上一步”导航按钮的 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 标记将用于表示单个分页项目符号。仅适用于'bullets'分页类型。

clickable布尔值false

如果为true,则单击分页按钮将导致过渡到相应的幻灯片。仅适用于项目符号分页类型

clickableClass字符串'swiper-pagination-clickable'

当分页可点击时设置的 CSS 类名

currentClass字符串'swiper-pagination-current'

"fraction" 分页中当前活动索引的元素的 CSS 类名

dynamicBullets布尔值false

如果你使用带有大量幻灯片的项目符号分页,最好启用此功能。因此,它将同时保持只有几个项目符号可见。

dynamicMainBullets数字1

启用dynamicBullets时可见的主项目符号数。

el任意null

带有分页容器的 CSS 选择器或 HTML 元素的字符串

enabled布尔值

与断点一起使用的布尔属性,用于在特定断点上启用/禁用分页

formatFractionCurrentfunction(number)

格式化分数分页当前数字。函数接收当前数字,你需要返回格式化的值

formatFractionTotalfunction(number)

格式化分数分页总数。函数接收总数,您需要返回格式化值

hiddenClass字符串'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 的direction参数相反,表示水平 swiper 方向的垂直进度条和垂直 swiper 方向的水平进度条

progressbarOppositeClass字符串'swiper-pagination-progressbar-opposite'

分页进度条相反的 CSS 类名

renderBulletfunction(index, className)

此参数允许完全自定义分页项目符号,您需要在此处传递一个函数,该函数接受分页项目符号的index编号和所需的元素类名 (className)。仅适用于'bullets'分页类型

const swiper = new Swiper('.swiper', {
  //...
  renderBullet: function (index, className) {
    return '<span class="' + className + '">' + (index + 1) + '</span>';
  }
});
renderCustomfunction(swiper, current, total)

此参数对于'custom'分页类型是必需的,您必须在此处指定如何呈现它。

const swiper = new Swiper('.swiper', {
  //...
  renderCustom: function (swiper, current, total) {
    return current + ' of ' + total;
  }
});
renderFractionfunction(currentClass, totalClass)

此参数允许自定义“分数”分页 html。仅适用于'fraction'分页类型

const swiper = new Swiper('.swiper', {
  //...
  renderFraction: function (currentClass, totalClass) {
      return '<span class="' + currentClass + '"></span>' +
              ' of ' +
              '<span class="' + totalClass + '"></span>';
  }
});
renderProgressbarfunction(progressbarFillClass)

此参数允许自定义“进度”分页。仅适用于'progress'分页类型

const swiper = new Swiper('.swiper', {
  //...
  renderProgressbar: function (progressbarFillClass) {
      return '<span class="' + progressbarFillClass + '"></span>';
  }
});
totalClass字符串'swiper-pagination-total'

“分数”分页中具有“快照”总数的元素的 CSS 类名

type'progressbar' | 'bullets' | 'fraction' | 'custom''bullets'

带有分页类型的字符串。可以是'bullets''fraction''progressbar''custom'

verticalClass字符串'swiper-pagination-vertical'

垂直 Swiper 中分页设置的 CSS 类名

分页方法

属性
swiper.bulletsHTMLElement[]

分页项目 HTML 元素的数组。若要获取特定的幻灯片 HTMLElement,请使用 swiper.pagination.bullets[1]

swiper.elHTMLElement

分页容器元素的 HTMLElement

方法
swiper.destroy()

销毁分页

swiper.init()

初始化分页

swiper.render()

呈现分页布局

swiper.update()

更新分页状态(启用/禁用/激活)

分页事件

名称参数描述
paginationHide(swiper)

在隐藏分页时触发事件

paginationRender(swiper, paginationEl)

在呈现分页后触发事件

paginationShow(swiper)

在显示分页时触发事件

paginationUpdate(swiper, paginationEl)

在更新分页时触发事件

分页 CSS 自定义属性

 {
  --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 类

dragSizenumber | 'auto''auto'

滚动条可拖动元素的大小(以像素为单位)

draggable布尔值false

设置为 true 以启用滚动条可拖动,以便控制滑块位置

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

设置为 true,以便在释放滚动条时将滑块位置捕捉到幻灯片

verticalClass字符串'swiper-scrollbar-vertical'

在垂直 Swiper 中设置的滚动条 CSS 类名

滚动条方法

属性
swiper.dragElHTMLElement

滚动条可拖动处理程序元素的 HTMLElement

swiper.elHTMLElement

滚动条容器元素的 HTMLElement

方法
swiper.destroy()

销毁滚动条

swiper.init()

初始化滚动条

swiper.setTranslate()

更新滚动条平移

swiper.updateSize()

更新滚动条轨道和处理程序大小

滚动条事件

名称参数描述
scrollbarDragEnd(swiper, event)

事件将在可拖动滚动条拖动结束时触发

scrollbarDragMove(swiper, event)

事件将在可拖动滚动条拖动移动时触发

scrollbarDragStart(swiper, event)

事件将在可拖动滚动条拖动开始时触发

滚动条 CSS 自定义属性

 {
  --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

过渡之间的延迟(以毫秒为单位)。如果未指定此参数,则自动播放将被禁用

如果您需要为特定幻灯片指定不同的延迟,可以使用幻灯片上的data-swiper-autoplay(以毫秒为单位)属性来实现。

<!-- hold this slide for 2 seconds -->
<div class="swiper-slide" data-swiper-autoplay="2000">
disableOnInteraction布尔值true

设置为 false,则自动播放不会在用户交互(滑动)后被禁用,它将在每次交互后重新启动

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

如果要在自由模式中禁用动量反弹,请将其设置为 false

momentumBounceRatio数字1

较高的值会产生更大的动量反弹效果

momentumRatio数字1

释放滑块后,较高的值会产生更大的动量距离

momentumVelocityRatio数字1

释放滑块后,较高的值会产生更大的动量速度

sticky布尔值false

设置为启用以启用在自由模式下捕捉幻灯片位置

网格

网格参数

名称类型默认值描述
fill'row' | 'column'“列”

可以是 “列”“行”。定义幻灯片应如何按列或按行填充行

如果与循环模式一起使用,请确保在循环模式要求中指定偶数个幻灯片,或启用 loopAddBlankSlides 参数

数字1

幻灯片行数,用于多行布局

操作

操作模块添加有用的 Swiper 方法来操作幻灯片。仅在 Swiper Core 版本中使用它才有意义,不打算与 Swiper React 或 Vue 一起使用。

操作方法

方法
swiper.addSlide(index, slides)

将新幻灯片添加到所需索引。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如

addSlide(1, '<div class="swiper-slide">Slide 10"</div>')

addSlide(1, [
 '<div class="swiper-slide">Slide 10"</div>',
 '<div class="swiper-slide">Slide 11"</div>'
]);
swiper.appendSlide(slides)

将新幻灯片添加到末尾。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如

appendSlide('<div class="swiper-slide">Slide 10"</div>')

appendSlide([
 '<div class="swiper-slide">Slide 10"</div>',
 '<div class="swiper-slide">Slide 11"</div>'
]);
swiper.prependSlide(slides)

将新幻灯片添加到开头。幻灯片可以是包含新幻灯片的 HTMLElement 或 HTML 字符串,或包含此类幻灯片的数组,例如

prependSlide('<div class="swiper-slide">Slide 0"</div>')

prependSlide([
 '<div class="swiper-slide">Slide 1"</div>',
 '<div class="swiper-slide">Slide 2"</div>'
]);
swiper.removeAllSlides()

移除所有幻灯片

swiper.removeSlide(slideIndex)

移除选定的幻灯片。slideIndex 可以是包含要移除的幻灯片索引的数字或包含索引的数组。

removeSlide(0); // remove first slide
removeSlide([0, 1]); // remove first and second slides
removeAllSlides();    // Remove all slides

视差

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

将进度/偏移限制为侧边幻灯片数量。如果为 1,则 prev/next 之后的幻灯片将具有相同的状态。如果为 2,则活动幻灯片之前/之后的第二个幻灯片将具有相同的状态,依此类推。

下一页CreativeEffectTransform

下一张幻灯片变换。

{
  // Array with translate X, Y and Z values
  translate: (string | number)[];
  // Array with rotate X, Y and Z values (in deg)
  rotate?: number[];
  // Slide opacity
  opacity?: number;
  // Slide scale
  scale?: number;
  // Enables slide shadow
  shadow?: boolean;
  // Transform origin, e.g. `left bottom`
  origin?: string;
}
透视布尔值true

如果自定义变换需要 3D 变换(translateZrotateXrotateY),请启用此参数

上一页CreativeEffectTransform

上一张幻灯片变换。接受以下类型的对象

{
  // Array with translate X, Y and Z values
  translate: (string | number)[];
  // Array with rotate X, Y and Z values (in deg)
  rotate?: number[];
  // Slide opacity
  opacity?: number;
  // Slide scale
  scale?: number;
  // Enables slide shadow
  shadow?: boolean;
  // Transform origin, e.g. `left bottom`
  origin?: string;
}
进度倍数数字1

允许乘以幻灯片变换和不透明度。

每进度阴影布尔值false

根据 limitProgress(仅在启用变换阴影时)为每张幻灯片拆分阴影“不透明度”(例如,设置 limitProgress: 2 并启用 shadowPerProgress,将把阴影不透明度设置为 0.51 在两个幻灯片旁边活动。禁用此参数后,所有幻灯片除了活动幻灯片外,都将具有不透明度为 1 的阴影

缩略图

除了 控制器 组件,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 进行包装。
  • 默认情况下,它期望缩放imgpicturecanvas元素之一。如果你想对其他自定义元素进行缩放,只需向此元素添加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

设置为true以启用键盘控制

onlyInViewport布尔值true

启用后,它将控制当前在视口中的滑块

pageUpDown布尔值true

启用后,它将通过 Page Up 和 Page Down 键启用键盘导航

键盘控制方法

属性
swiper.enabled布尔值

是否启用键盘控制

方法
swiper.disable()

禁用键盘控制

swiper.enable()

启用键盘控制

键盘事件

名称参数描述
keyPress(swiper, keyCode)

按下键盘时触发事件

鼠标滚轮控制

鼠标滚轮控制参数

名称类型默认值描述
enabled布尔值false

设置为 true 以启用鼠标滚轮控制

eventsTarget任意'container'

接受鼠标滚轮事件的容器的 CSS 选择器或 HTML 元素的字符串。默认情况下为 swiper

forceToAxis布尔值false

设置为 true 以强制鼠标滚轮滑动到轴。因此,在水平模式下,鼠标滚轮仅适用于水平鼠标滚轮滚动,在垂直模式下仅适用于垂直滚动。

invert布尔值false

设置为 true 以反转滑动方向

noMousewheelClass字符串'swiper-no-mousewheel'

将忽略具有此类的元素上的滚动

releaseOnEdges布尔值false

设置为 true,当 swiper 处于边缘位置(开始或结束)时,swiper 将释放鼠标滚轮事件并允许页面滚动

sensitivity数字1

鼠标滚轮数据的乘数,允许调整鼠标滚轮灵敏度

thresholdDeltanull | 数字null

触发 swiper 幻灯片更改的最小鼠标滚轮滚动增量

thresholdTimenull | 数字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

是否启用虚拟幻灯片

renderExternalfunction(data)

用于外部渲染的函数(例如,使用其他一些库来处理 DOM 操作和状态,如 React.js 或 Vue.js)。它接受一个带有以下属性的 data 对象作为参数

  • offset - 幻灯片向左/向上的偏移量(以像素为单位)
  • from - 需要渲染的第一张幻灯片的索引
  • to - 需要渲染的最后一张幻灯片的索引
  • slides - 要渲染的幻灯片项的数组
renderExternalUpdate布尔值true

当启用时(默认情况下),它将在调用 renderExternal 之后立即更新 Swiper 布局。当与异步渲染的渲染库一起使用时,禁用并手动更新 swiper 很有用

renderSlidefunction(slide, index)

用于渲染幻灯片的函数。它接受 slides 数组的当前幻灯片项和当前幻灯片的索引号作为参数。函数必须返回 swiper 幻灯片的外部 HTML 或幻灯片 HTML 元素。

slidesT[][]

包含幻灯片的数组

虚拟幻灯片方法

属性
swiper.cache对象

包含缓存的幻灯片 HTML 元素的对象

swiper.from数字

第一个渲染幻灯片的索引

swiper.slidesT[]

virtual.slides 参数传递的幻灯片项数组

swiper.to数字

最后渲染幻灯片的索引

方法
swiper.appendSlide(slide)

追加幻灯片。slides 可以是单个幻灯片项目,也可以是包含此类幻灯片的数组。

仅适用于核心版本(在 React 和 Vue 中,应通过修改幻灯片数组/数据/源来完成此操作)

swiper.prependSlide(slide)

前置幻灯片。slides 可以是单个幻灯片项目,也可以是包含此类幻灯片的数组。

仅适用于核心版本(在 React 和 Vue 中,应通过修改幻灯片数组/数据/源来完成此操作)

swiper.removeAllSlides()

移除所有幻灯片

仅适用于核心版本(在 React 和 Vue 中,应通过修改幻灯片数组/数据/源来完成此操作)

swiper.removeSlide(slideIndexes)

移除特定幻灯片或幻灯片。slideIndexes 可以是带有要移除的幻灯片索引的数字,也可以是带有索引的数组。

仅适用于核心版本(在 React 和 Vue 中,应通过修改幻灯片数组/数据/源来完成此操作)

swiper.update(force)

更新虚拟幻灯片状态

虚拟幻灯片 Dom

从版本 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,
});

哈希导航参数

名称类型默认值描述
getSlideIndexfunction(swiper, hash)

旨在与虚拟幻灯片一起使用,当无法通过哈希在 DOM 中找到幻灯片时(例如尚未呈现)

replaceState布尔值false

除了 hashnav 之外,还用于将当前 URL 状态替换为新状态,而不是将其添加到历史记录中

watchState布尔值false

设置为 true 以启用通过浏览器历史记录或直接在文档位置设置哈希来导航幻灯片(当启用 hashnav 时)

哈希导航事件

名称参数描述
hashChange(swiper)

窗口哈希值更改时触发事件

hashSet(swiper)

Swiper 更新哈希值时触发事件

历史导航

历史导航参数

名称类型默认值描述
enabled布尔值false

启用历史插件。

keepQuery布尔值false

更改浏览器 URL 时保留查询参数。

key字符串'slides'

幻灯片的 URL 键

replaceState布尔值false

除了 hashnav 或历史记录外,还可以替换当前 URL 状态,而不是将其添加到历史记录中

root字符串''

Swiper 页面根目录,当您在非根网站页面上使用 Swiper 历史模式时指定此项非常有用。例如,可以是 https://my-website.com/https://my-website.com/subpage//subpage/

控制器

控制器参数

名称类型默认值描述
by'slide' | 'container'“滑动”

定义控制另一个滑块的方式:逐个幻灯片(相对于其他滑块的网格)或根据所有幻灯片/容器(取决于总滑块百分比)。

control任意

在此处传递另一个 Swiper 实例或包含应由该 Swiper 控制的 Swiper 实例的数组。还接受带有 Swiper 元素 CSS 选择器的字符串或 Swiper 元素的 HTMLElement

inverse布尔值false

设置为 true,控制将按相反方向进行

控制器方法

属性
swiper.control任意

在此处传递另一个 Swiper 实例或包含应由该 Swiper 控制的 Swiper 实例的数组

辅助功能 (a11y)

辅助功能参数

名称类型默认值描述
containerMessagenull | 字符串null

屏幕阅读器用于外部 swiper 容器的消息

containerRoleDescriptionMessagenull | 字符串null

用于屏幕阅读器描述外部 swiper 容器角色的消息

enabled布尔值true

启用 A11y

firstSlideMessage字符串“这是第一张幻灯片”

当 swiper 处于第一张幻灯片时,用于屏幕阅读器上一个按钮的消息

idnull | string | numbernull

要设置在 swiper-wrapper 上的 id 属性的值。如果为 null,将自动生成

itemRoleDescriptionMessagenull | 字符串null

用于屏幕阅读器描述幻灯片元素角色的消息

lastSlideMessage字符串“这是最后一张幻灯片”

当 swiper 处于最后一张幻灯片时,用于屏幕阅读器下一个按钮的消息

nextSlideMessage字符串“下一张幻灯片”

用于屏幕阅读器上一个按钮的消息

notificationClass字符串“swiper-notification”

A11y 通知的 CSS 类名

paginationBulletMessage字符串“转到幻灯片 {{index}}”

用于屏幕阅读器描述单个分页项目的消息

prevSlideMessage字符串“上一张幻灯片”

用于屏幕阅读器上一个按钮的消息

slideLabelMessage字符串“{{index}} / {{slidesLength}}”

用于屏幕阅读器描述幻灯片元素标签的消息

slideRole字符串“group”

swiper 幻灯片 role 属性的值

自定义构建

你有两个选项可以制作自定义版本的 Swiper。

使用 JS 模块

如果你在你的项目中使用支持 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 构建器,允许构建自定义库版本,其中你只能包含必需的模块。我们需要以下内容

  1. 下载并解压 Swiper GitHub 存储库 到本地文件夹

  2. 安装 Node.js(如果未安装)

  3. 现在,我们需要安装必需的依赖项。转到下载并解压的 Swiper 存储库文件夹,并在终端中执行

    $ npm install
    
  4. 打开 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',
      ],
    };
    
  5. 现在,我们准备构建 Swiper 的自定义版本

    $ npm run build:prod
    
  6. 就是这样。生成的 CSS 和 JS 文件及其缩小版本将在 dist/ 文件夹中提供。

TypeScript 定义

Swiper 完全类型化,它导出 SwiperSwiperOptions 类型

// 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 定义浏览器 以了解所有类型、选项、属性和方法。