轮播图

@Swiper

简介 Overview

.目前最新版为11；注意：不同的版本，使用方法略有不同。。。

.更多细节，请访问 https://www.swiper.com.cn 或 https://swiperjs.com/[推荐]；请首先阅读 Get Started 和 Demos 两部分内容

核心文件 Core

.可以下载后本地使用，也可以使用在线CDN https://cdnjs.com/

.引入样式库 swiper-bundle.min.css

<link rel="stylesheet" href="/utils/lib/swiper-11.0.5/package/swiper-bundle.min.css">

.引入逻辑库 swiper-bundle.min.js

<script src="/utils/lib/swiper-11.0.5/package/swiper-bundle.min.js"></script>

基本结构 HTML

可以使用任何标签实现结构，保持库类名相同即可

.swiper

.swiper-wrapper

.swiper-slide

... ...

.swiper-slide

.swiper-pagination [分页器，可选]

.swiper-button-prev [导航按钮；可选]

.swiper-button-next [导航按钮；可选]

.swiper-scrollbar [滚动条；可选]

1. 默认结构 - <div>

<div class="team-swiper swiper">
  <div class="swiper-wrapper">
    <div class="team-card swiper-slide">Slide 1</div>
    <div class="team-card swiper-slide">Slide 2</div>
    <div class="team-card swiper-slide">Slide 3</div>
    ...
  </div>

  <div class="swiper-pagination"></div>

  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>

  <div class="swiper-scrollbar"></div>
</div>

2. 建议结构 - <ul> <li>

<div class="promotion-swiper swiper">
  <ul class="swiper-wrapper">
    <li class="promotion-card swiper-slide">Slide 1</li>
    <li class="promotion-card swiper-slide">Slide 2</li>
    <li class="promotion-card swiper-slide">Slide 3</li>
    ...
  </ul>

  <div class="swiper-pagination"></div>

  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>

  <div class="swiper-scrollbar"></div>
</div>

样式 CSS

.容器 swiper

.相对定位；为分页器 pagination 提供定位依据

.指定内容大小[可选]；如图片的显示，可以指定宽高或宽高比

.不建议使用背景图片 - 渲染可能有异常

.F12检查并修改对应的类重置样式

.自定义样式通常需要提权

.swiper {
  width: 100%;
  max-width: 800px;
}

脚本 JavaScript

.指定 swiper 的初始化和各种选项

const swiper = new Swiper('.swiper', {
  // Optional parameters
  direction: 'vertical',
  loop: true,
  clickable: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',
  },
});

.多个轮播图时，使用自定义类区分，如增加 team-swiper 和 team-card

const teamSwiper = new Swiper('.team-swiper', {});

选项 Option

参数 Parameters

.实例化的同时，配置轮播图基本参数；更多参数，请访问轮播图 - Parameters

.值对形式 key-value

const swiper = new Swiper('.swiper', {
  // 各配置项
});

参数
类别	说明
direction	轮播方向：horizontal \| vertical
autoplay	自动播放：false \| true
breakpoints	断点设置；仅支持部分属性，如 spaceBetween、slidesPerView等
centeredSlides	居中当前幻灯，适合多个幻灯的情况；false \| true \| auto*
effect	过渡效果；slide \| fade \| cube \| coverflow \| flip \| creative \| cards
xxxeffect	配合effect进一步定制过渡效果，如cubeeffect
grabCursor	抓取\|拖拽鼠标样式，概述桌面端体验：false \| true
loop	循环模式；false \| true
mousewheel	鼠标滚轮触发导航：false \| true
slidesPerView	轮播时可以查看幻灯片的个数；默认1张；auto时，
spaceBetween	幻灯片间隔；单位px；不要为幻灯片指定margin
speed	幻灯过渡时间；单位ms；300
on	注册事件处理

属性 Properties

.轮播图实例化后，可以使用相应的属性和方法实现参数的功能；更多信息，请访问轮播图 - Methods & Properties

swiper.autoplay

属性
分类	说明
activeIndex	当前活动幻灯片；循环模式下容易出现异常
realIndex	幻灯片实际索引；推荐使用
autoplay	自动播放；鼠标点击修改该属性，仍然会播放一次才停止
mousewheel	使用鼠标滚轮导航

方法 Methods

.更多信息，请访问轮播图 - Methods & Properties

swiper.init()

方法
分类	说明
init(el)	初始化
swiper.on(event, handler)	注册事件

事件 Events

.同轮播图的交互；支持两种形式；更多信息，请访问轮播图 - Events

.尽量不要使用箭头函数，避免 this 丢失

配置形式

const swiper = new Swiper('.swiper', {
  // ...
  on: {
    init: function () {
      console.log('swiper initialized');
    },
  },
});

实例形式

const swiper = new Swiper('.swiper', {
  // ...
});
swiper.on('slideChange', function () {
  console.log('slide changed');
});

事件
分类	说明
init	初始化
slideChange	当前活动幻灯切换完毕

分页器 Pagination

.基类是 swiper-pagination

.不同的分页器类型有不同的类实现，如子弹类分页器是 swiper-pagination-bullets；分数类型分页器是 swiper-pagination-fraction

.辅助类 swiper-pagination-horizontal

.如果仅仅是定义样式，不修改数字格式，可以直接使用默认类重新定制

.如果需要定制分页器的结构，则需要使用专门的配置项定制

.使用绝对定位；默认在底部居中，可以定位在任何地方

.可以使用全局变量指定导航按钮样式

分页器 pagination
参数	说明
type	类型；进度条 progressbar \| 子弹 bullets，默认 \| 分数 fraction \| 自定义 custom 每个类型都可进一步定制
clickable	单击分页跳转到对应页面，默认为 false
bulletClass	和子弹类型分页器相关的默认类；swiper-pagination-bullet-custom
dynamicBullets	突出/动态展示少量页码；默认是 false
renderBullet	(index,className) => {} 定制子弹类型分页器；返回定制的DOM结构
currentClass	和分数类型分页器相关的默认类；swiper-pagination-current
totalClass	和分数类型分页器相关的默认类；swiper-pagination-total
renderFraction	(currentClass, totalClass) => {} 定制分数类型分页器；返回定制的DOM结构
renderCustom	定制和自定义类型custom相关的分页器；function(swiper, current, total)

.swiper .swiper-pagination-bullet {
  width: 14px;
  height: 14px;
  background-color: #fff;
}

.swiper .swiper-pagination-bullet-active {
  background-color: #f40;
}

或

.swiper-pagination-bullet {
  background-color: transparent;
  width: 40px;
  height: 8px;
  border: 1px solid #fff;
  border-radius: 4px;
  opacity: 1;
}

.swiper-pagination-bullet-active {
  background-color: #f40;
}

导航按钮 button

直接修改

.swiper-button-prev,
.swiper-button-next {
    color: var(--main-color);
}

添加自定义类，指定缩放、颜色、悬停、空白等等样式，甚至响应移动端时，将其隐藏

.swiper .swiper-btn {
  width: 16px;
  height: 16px;
  color: #fff;
  transform: scale(0.6);
}

.swiper .swiper-btn:hover {
  color: var(--pri-color);
}

滚动条 scrollbar

--swiper-navigation-size: 36px;
--swiper-navigation-color: #fff;

案例 Cases

顶部轮播图 - 响应式设置

默认显示1张幻灯，间隔10px

达到768时，显示2张，间隔增加到15px

达到1024时，显示3张，间隔增加到20px

let swiper = new Swiper('.header-swiper', {
  //... ...
  slidesPerView: 1,
  spaceBetween: 10,
  breakpoints: {
    768: {
      slidesPerView: 2,
      spaceBetween: 15
    },
    1024: {
      slidesPerView: 3,
      spaceBetween: 20
    },
  }
});

定制子弹类分页器

当前样式 - 背景红色

.swiper-pagination-bullet-active {
  background-color: #f40;
}

点到圆角矩形的变化

.swiper-pagination-bullet {
  width: 8px;
  height: 8px;
  border-radius: 4px;
  transition: width .4s;
}

.swiper-pagination-bullet-active {
  width: 20px;
  background-color: #f40;
}

定位在右侧居中；注意初始化属性 initial 的使用

.swiper-pagination-bullets.swiper-pagination-horizontal {
  width: initial;
  left: initial;
  height: 100%;
  right: 0;
  top: 0;
  display: flex;
  flex-direction: column;
  justify-content: center;
  gap: 10px;
}

定制子弹类型分页器；完整案例请访问靓车荟 - Cars

默认样式是1 2 3；定制样式为01 02 03，结构发生变化，需要使用renderBullet属性专门定制

const swiper = new Swiper('.swiper', {
  loop: true,
  autoplay: true,
  speed: 1200,
  effect: 'fade',
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
    renderBullet: function (index, className) {
      return '' + String(index + 1).padStart(2, '0') + '';
    }
  }
});

.swiper {
  width: 100%;
  max-width: 800px;
  aspect-ratio: 4/3;
}

.swiper-slide {
  position: relative;
}

.swiper-slide img {
  position: absolute;
  transform: translateX(50%);
  width: 100%;
  opacity: 0;
  transition: 0.4s;
}

.swiper-pagination-bullets.swiper-pagination-horizontal {
  bottom: 20px;
  display: flex;
  justify-content: center;
}

.swiper-pagination-bullets .swiper-pagination-bullet {
  width: 20px;
  padding: 4px 10px;
  display: grid;
  place-items: center;
  border-radius: 10px;
  background: none;
  opacity: 1;
  align-content: center;
  font-size: 12px;
  color: #000;
  margin: 0;
  border: 1px solid transparent;
}

.swiper-pagination-bullets .swiper-pagination-bullet-active {
  border-color: #000;
}

.swiper-slide-active img {
  transform: translateX(0);
  opacity: 1;
}

定制分数类型分页器

默认样式 1/8

定制样式01/08

因为Swiper没有直接支持分数型且带补零的分页类型，所以我们使用自定义类型的分页器，并通过renderCustom回调来控制其显示内容

参考源码

function formatFraction(currentIndex, totalSlides) {
  const formattedCurrent = String(currentIndex).padStart(2, "0");
  const formattedTotal = String(totalSlides).padStart(2, "0");
  return `<span class="swiper-pagination-current">${formattedCurrent}</span>/<span class="swiper-pagination-total">${formattedTotal}</span>`;
}

const swiper = new Swiper(".swiper", {
  loop: true,
  autoplay: true,
  speed: 1200,
  effect: "fade",
  pagination: {
    el: ".swiper-pagination",
    type: "custom", // 使用自定义分页器类型
    renderCustom: function (swiper, current, total) {
      return formatFraction(current, total); // 直接引用formatFraction函数
    },
  },
  on: {
    init: function () {
      // 初始化时更新分页器文本
      this.pagination.renderedFraction = formatFraction(
        this.activeIndex + 1,
        this.slides.length
      );
    },
    slideChange: function () {
      // 每当幻灯片变化时更新分页器文本
      this.pagination.renderedFraction = formatFraction(
        this.activeIndex + 1,
        this.slides.length
      );
    },
  },
});

每次幻灯片切换时，为其中的内容 swiperInfo 添加 anime 动画 - 个人网站

同时使用 Anime.js库

const swiperInfo = document.querySelectorAll('.swiper-info')

const swiper = new Swiper('.swiper', {
  // ...
});

swiper.on('slideChange', function () {
  console.log('slide changed');
  anime({
    targets: swiperInfo[swiper.realIndex].children,
    opacity: [0, 1],
    duration: 400,
    easing: "linear",
    delay: anime.stagger(400, { start: 300 }),
    translateY: [anime.stagger(40, 10), 0],
  })
});