怎么使用 Swiper.js 制作带缩略图控制的画廊效果

一、画廊与缩略图双实例联动原理

初次制作画廊效果时，很多开发者容易尝试在一个 Swiper 容器内通过复杂的 CSS 去同时处理大图展示与下方小图列表。然而，大图展示与缩略图在交互逻辑上有着本质差异：大图要求单帧全宽展示（slidesPerView: 1）、强调手势滑动与视窗居中；缩略图则需要同时呈现多张小图（如 slidesPerView: 4 或更多）、支持自由滑动（freeMode），并兼任视觉导航控制器。

为了实现优雅解耦，Swiper.js 提供了专门的 Thumbs 模块。它的运作逻辑建立在“主从协同”基础上：

• 主画廊负责展现内容：作为用户主要的视觉焦点，监听滑动、拖拽与方向键交互，并在当前展示页码变化时，向挂载的缩略图实例下发索引更新指令。
• 缩略图负责状态导航：作为辅助控制栏，每一个小图滑块均绑定了点击事件，点击时主动调用主实例的跳转接口；同时响应主图下发的同步指令，切换自身激活样式。
• 关键桥梁 watchSlidesProgress：该参数指示缩略图实例时刻计算并广播各 Slide 在视窗中的投影比例与激活状态。缺少这一选项，主 Swiper 将无法捕获目标缩略图的位置，导致联动高亮失效。

二、标准制作步骤与代码实现

实现这一效果分为四个明确步骤：引入资源库、搭设双层 DOM 容器、配置 CSS 状态规则，以及按正确顺序执行 JavaScript 实例化绑定。

第 1 步：引入依赖与搭建 HTML 骨架

首先在 HTML 中载入 Swiper 官方的样式表与 JavaScript 核心脚本。可以通过主流 CDN 引入，也可以在现代前端工程中通过包管理器引入。

在页面主体中，分别声明主画廊容器（如 .gallery-top）与缩略图容器（如 .gallery-thumbs）。两者的内部结构均严格遵循 Swiper 标准规范：外层 .swiper、中层 .swiper-wrapper、内层各子项 .swiper-slide。需要特别注意的是，主画廊与缩略图内的 Slide 数量必须严格一一对应。

<!-- 引入 Swiper 样式与脚本 (以 Swiper 11 为例) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css" />
<script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js"></script>

<!-- 画廊最外层包裹器 -->
<div class="gallery-wrapper">
  <!-- 1. 主画廊视窗容器 -->
  <div class="swiper gallery-top">
    <div class="swiper-wrapper">
      <div class="swiper-slide"><img src="img1-large.jpg" alt="画廊展图 1"></div>
      <div class="swiper-slide"><img src="img2-large.jpg" alt="画廊展图 2"></div>
      <div class="swiper-slide"><img src="img3-large.jpg" alt="画廊展图 3"></div>
      <div class="swiper-slide"><img src="img4-large.jpg" alt="画廊展图 4"></div>
    </div>
    <!-- 导航切换箭头 -->
    <div class="swiper-button-next"></div>
    <div class="swiper-button-prev"></div>
  </div>

  <!-- 2. 缩略图控制栏容器 -->
  <div class="swiper gallery-thumbs">
    <div class="swiper-wrapper">
      <div class="swiper-slide"><img src="img1-thumb.jpg" alt="缩略图 1"></div>
      <div class="swiper-slide"><img src="img2-thumb.jpg" alt="缩略图 2"></div>
      <div class="swiper-slide"><img src="img3-thumb.jpg" alt="缩略图 3"></div>
      <div class="swiper-slide"><img src="img4-thumb.jpg" alt="缩略图 4"></div>
    </div>
  </div>
</div>

三、关键 CSS 布局与高亮状态控制

为了呈现主次分明的视觉效果，必须对主画廊和缩略图的高宽比例进行区分。通常主画廊占据大部分高度，而缩略图则保持为紧凑的水平条带。

更重要的是状态样式的编写。Swiper 在检测到缩略图被激活时，会自动为其所在的 Slide 添加类名 .swiper-slide-thumb-active。我们可以利用这个类名，让非激活项保持较低透明度（如 0.45），而在激活项上施加 1.0 的完全不透明度与明显的边框高亮。

/* 画廊容器基准设置 */
.gallery-wrapper {
  max-width: 800px;
  margin: 0 auto;
}

/* 1. 主画廊高度与图片填充满 */
.gallery-top {
  width: 100%;
  height: 420px;
  border-radius: 8px;
  overflow: hidden;
  background-color: #000000;
}
.gallery-top .swiper-slide img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  display: block;
}

/* 2. 缩略图栏目高度与间距 */
.gallery-thumbs {
  width: 100%;
  height: 90px;
  margin-top: 12px;
}
.gallery-thumbs .swiper-slide {
  height: 100%;
  border-radius: 6px;
  overflow: hidden;
  cursor: pointer;
  opacity: 0.45; /* 未选中项半透明 */
  transition: opacity 0.3s ease, border-color 0.3s ease;
  box-sizing: border-box;
}
.gallery-thumbs .swiper-slide img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  display: block;
}

/* 3. 缩略图悬停与激活态高亮 */
.gallery-thumbs .swiper-slide:hover {
  opacity: 0.8;
}
.gallery-thumbs .swiper-slide-thumb-active {
  opacity: 1;
  border: 2px solid #71A397; /* 灰绿主色高亮边框 */
}

四、JavaScript 初始化与双向互锁绑定

进入脚本初始化阶段，必须遵循“缩略图先行、主画廊后挂载”的次序法则。

原因非常明确：在创建主画廊实例时，配置项 thumbs: { swiper: thumbsSwiper } 需要引用已经存在的缩略图实例对象。如果反向操作，传入的变量值将为 undefined，导致主画廊无法在其内部挂载监听器。

// 步骤一：先初始化缩略图 Swiper 实例
const thumbsSwiper = new Swiper('.gallery-thumbs', {
  spaceBetween: 10,           // 缩略图间距 (px)
  slidesPerView: 4,           // 默认视窗内展示 4 个小图
  freeMode: true,             // 开启自由滑动，手指拖拽时不按固定栅格贴靠
  watchSlidesProgress: true,  // ★ 核心：计算每个小图的可见进度，供主图精准捕获
  touchRatio: 0.8,            // 优化手势滑动灵敏度
});

// 步骤二：再初始化主画廊 Swiper 实例，并将 thumbsSwiper 挂载传入
const mainSwiper = new Swiper('.gallery-top', {
  spaceBetween: 10,           // 主图切换间距
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  thumbs: {
    swiper: thumbsSwiper,     // 建立双向互锁通道
  },
});

在这段脚本中，各配置项协同工作：

• spaceBetween: 10：在 Slide 之间建立均匀间隔，配合 CSS 边框保证美观。
• freeMode: true：缩略图列表不需要像大图那样翻一整屏，开启自由滑动可以让用户快速扫过几十张缩略小图。
• watchSlidesProgress: true：实时计算缩略图当前滚动的像素偏移和元素露出比例，是 Thumbs 模块生效的底层支撑。
• thumbs: { swiper: thumbsSwiper }：将缩略图实例的引用注入主图，两者的索引联动与自动居中机制即刻启动。

五、常见问题排查与避坑指南

在实际开发中，关于 Swiper 缩略图控制有三个高频踩坑点，遇到效果异常时可按以下对照矩阵自查：

1. 点击缩略图大图不跳转，或滑动大图缩略图不高亮

排查顺序：首先检查缩略图初始化配置中是否遗漏了 watchSlidesProgress: true。其次检查浏览器的控制台，确认两个实例初始化的上下次序。如果主画廊在缩略图之前实例化，thumbs.swiper 捕获的值为空，整个联动就会在静默中失败。

2. 循环模式（loop: true）下出现跳动或错位

当你在主画廊开启 loop: true 时，Swiper 会克隆首尾两个 Slide 以营造无缝回环。如果此时缩略图没有开启 loop，或者两个实例的基础 Slide 总数小于 slidesPerView 的 2 倍，就会出现点击第 1 张跳到最后一张、或者高亮框与实际图片对不上的现象。

3. 异步获取图片数据后画廊联动失效

在 Vue、React 或通过 fetch 动态渲染 DOM 时，图片节点是在 JavaScript 初始化之后插入的。此时 Swiper 内部计算的宽度与 Slide 总数为 0。必须在数据加载并完成 DOM 渲染后，手动调用更新方法：

// 动态插入数据后重新计算几何尺寸
thumbsSwiper.update();
mainSwiper.update();

六、响应式适配与进阶实践

在桌面端，屏幕较宽，缩略图可以同时呈现 5~6 项；在移动端，屏幕窄小，通常只展示 3~4 项。可以通过 Swiper 的 breakpoints 参数实现优雅的响应式阶梯适配：

const thumbsSwiper = new Swiper('.gallery-thumbs', {
  spaceBetween: 8,
  slidesPerView: 3,           // 默认小屏呈现 3 列
  freeMode: true,
  watchSlidesProgress: true,
  breakpoints: {
    640: {
      slidesPerView: 4,       // 平板宽度呈现 4 列
      spaceBetween: 10,
    },
    1024: {
      slidesPerView: 5,       // 桌面大屏呈现 5 列
      spaceBetween: 12,
    },
  },
});

七、总结

使用 Swiper.js 制作带缩略图控制的画廊效果，关键不是堆叠复杂的监听逻辑，而是合理利用其内置的 Thumbs 模块完成主从绑定。牢记以下关键要点，即可在实际项目中高效落地该功能：

1. 容器分立：主画廊与缩略图使用各自独立的 .swiper 容器，保持内部 Slide 数量与顺序一致。
2. 先行初始化：缩略图实例必须先行完成构造，再作为参数注入主画廊实例。
3. 进度监听：缩略图配置中必须声明 watchSlidesProgress: true。
4. 视觉反馈：通过 .swiper-slide-thumb-active 类名明确定义当前选中的高亮样式。