Swiper.js 怎么实现多行多列的卡片滑动布局

图 0：Swiper.js 多行多列卡片网格滑动视觉示意

一、多行多列网格的运作机制与必要条件

很多开发者在早期接触 Swiper 时，习惯了单行横向滚动的模式。当需要展示“一行 3 个、一共 2 行，左右成组滑动”的商品卡片、快捷导航或图片列表时，往往会尝试直接用普通的 CSS Grid 包装 slide，这会导致 Swiper 内部位移计算失效。

从 Swiper 7 开始，官方废弃了早期的 slidesPerColumn 参数，将其完全重构为独立的 Grid 模块。要让多行多列网格正确渲染，底层必须满足两个几何计算条件：

1. 行高依赖容器高度：与单行滑动依靠内容撑开高度不同，多行布局中每张卡片的高度是由 (容器总高度 - 行间距总和) / 行数 计算出来的。如果外部 .swiper 容器未设置高度（即 height: auto），计算结果将为 0 或产生垂直堆叠折叠。
2. 列宽依赖容器宽度：卡片的宽度则由 (容器总宽度 - 列间距总和) / slidesPerView 决定。

图 1：Swiper 多行网格布局计算原理与尺寸依赖

二、四步实现多行多列卡片滑动

实现该布局无需复杂的 DOM 嵌套，按照标准操作顺序可以分为：搭建结构、约束容器高度、导入并初始化 Grid 模块、补充响应式断点四步。

图 2：Swiper.js 多行多列卡片布局 4 步落地流程

第 1 步：规范 HTML 骨架

与普通单行 Swiper 一致，HTML 中依然保持扁平的单层 .swiper-wrapper 和多个平铺的 .swiper-slide，不要在 HTML 里手动为每行创建额外的包裹 div：

<!-- 容器根节点 -->
<div class="swiper my-grid-swiper">
  <!-- 统一的轨道容器，无需多层行嵌套 -->
  <div class="swiper-wrapper">
    <div class="swiper-slide"><div class="card">卡片 01</div></div>
    <div class="swiper-slide"><div class="card">卡片 02</div></div>
    <div class="swiper-slide"><div class="card">卡片 03</div></div>
    <div class="swiper-slide"><div class="card">卡片 04</div></div>
    <div class="swiper-slide"><div class="card">卡片 05</div></div>
    <div class="swiper-slide"><div class="card">卡片 06</div></div>
    <div class="swiper-slide"><div class="card">卡片 07</div></div>
    <div class="swiper-slide"><div class="card">卡片 08</div></div>
    <div class="swiper-slide"><div class="card">卡片 09</div></div>
    <div class="swiper-slide"><div class="card">卡片 10</div></div>
    <div class="swiper-slide"><div class="card">卡片 11</div></div>
    <div class="swiper-slide"><div class="card">卡片 12</div></div>
  </div>

  <!-- 可选的分页器与导航按钮 -->
  <div class="swiper-pagination"></div>
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
</div>

第 2 步：为 Swiper 容器设定明确高度

这是多行网格最容易踩坑的环节。必须在 CSS 中给 .swiper 指定一个确切的高度。同时引入基础样式以及网格专用样式：

/* 基础样式中必须包含 Swiper 样式与 Grid 样式 */
/* 如果使用 NPM:
   import 'swiper/css';
   import 'swiper/css/grid';
   import 'swiper/css/pagination';
*/

.my-grid-swiper {
  width: 100%;
  /* 关键：必须设置固定高度或基于视口/容器的明确高度 */
  height: 460px;
  margin: 0 auto;
}

/* 卡片内部自定义样式 */
.swiper-slide {
  /* 确保卡片填满所在网格单元格 */
  height: calc((100% - 20px) / 2) !important;
  display: flex;
  justify-content: center;
  align-items: center;
}

.card {
  width: 100%;
  height: 100%;
  background: #FFFFFF;
  border: 1px solid #E2E8F0;
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: 500;
  color: #4F6272;
}

第 3 步：初始化参数并启用 Grid 模块

在 JavaScript 初始化时，配置 modules: [Grid, Pagination]，并在参数对象中传入 slidesPerView 与 grid：

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

const swiper = new Swiper('.my-grid-swiper', {
  // 1. 注册核心功能模块
  modules: [Grid, Pagination, Navigation],

  // 2. 水平排列列数（每屏显示 3 列）
  slidesPerView: 3,

  // 3. 配置网格参数：行数与填充方向
  grid: {
    rows: 2,          // 每页显示 2 行
    fill: 'row',      // 'row' 表示按行填充，'column' 表示按列填充
  },

  // 4. 卡片间距（单位：px）
  spaceBetween: 20,

  // 5. 分页器与控制
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
});

三、卡片排列方式：fill: 'row' 与 fill: 'column' 的本质差异

Swiper 提供了两种填充算法，由 grid.fill 参数控制。理解两者的差异对于正确呈现卡片顺序至关重要：

• fill: 'column'（默认值）：元素按“从上到下排满一列，再排下一列”的方式填充。例如在 2 行 3 列布局中，第一页卡片顺序为：第一列（1, 2）、第二列（3, 4）、第三列（5, 6）。这会导致视觉上第一行的卡片编号是不连续的奇数（1, 3, 5），通常违背用户的自然从左往右阅读习惯。
• fill: 'row'（业务推荐）：元素按“从左到右填满一行，再折行填下一行”的方式填充。第一行显示（1, 2, 3），第二行显示（4, 5, 6）。这种流动模式与常规网页列表完全一致，符合绝大多数卡片瀑布流或网格展示的需求。

图 3：卡片排列流向对比：fill: 'column'（默认） vs fill: 'row'（推荐）

四、响应式多端适配（Breakpoints）

在移动端和桌面端，屏幕宽度差异极大。通常在手机竖屏时采用 1 行 2 列或 2 行 1 列，而在平板展示 2 行 2 列，桌面端展示 2 行 3 列或 2 行 4 列。Swiper 允许在 breakpoints 中针对不同屏幕宽度动态修改 slidesPerView 与 grid.rows：

const swiper = new Swiper('.my-grid-swiper', {
  modules: [Grid, Pagination, Navigation],
  spaceBetween: 16,
  grid: {
    fill: 'row',
  },
  // 响应式断点设置
  breakpoints: {
    // 移动端（屏幕宽度 >= 320px）：2行 1列
    320: {
      slidesPerView: 1,
      grid: {
        rows: 2,
      },
      spaceBetween: 12,
    },
    // 平板端（屏幕宽度 >= 768px）：2行 2列
    768: {
      slidesPerView: 2,
      grid: {
        rows: 2,
      },
      spaceBetween: 16,
    },
    // 桌面端（屏幕宽度 >= 1024px）：2行 3列
    1024: {
      slidesPerView: 3,
      grid: {
        rows: 2,
      },
      spaceBetween: 20,
    },
  },
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
});

五、关键限制与避坑备忘

在多行多列网格模式下，Swiper 有几个核心边界限制与常见错误需要重点留意：

图 4：Swiper.js Grid 模块核心规则与避坑备忘

六、完整独立运行示例（CDN 单文件版）

如果需要在简单页面中快速验证或以 CDN 方式引入，可以使用预打包的完整版 swiper-bundle，无需手动引入各个单独模块：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Swiper Grid 示例</title>
  <!-- 引入 Swiper 完整样式 -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css" />
  <style>
    body {
      background-color: #F8F9FA;
      padding: 40px 20px;
      font-family: sans-serif;
    }
    .demo-container {
      max-width: 800px;
      margin: 0 auto;
    }
    /* 必须设置高度 */
    .swiper {
      width: 100%;
      height: 420px;
      padding-bottom: 40px; /* 给分页器留出空间 */
    }
    .swiper-slide {
      background: #FFFFFF;
      border: 1px solid #E2E8F0;
      border-radius: 8px;
      display: flex;
      align-items: center;
      justify-content: center;
      font-size: 18px;
      font-weight: bold;
      color: #4F6272;
      box-shadow: 0 2px 6px rgba(0,0,0,0.04);
    }
  </style>
</head>
<body>
  <div class="demo-container">
    <div class="swiper mySwiper">
      <div class="swiper-wrapper">
        <div class="swiper-slide">卡片 1</div>
        <div class="swiper-slide">卡片 2</div>
        <div class="swiper-slide">卡片 3</div>
        <div class="swiper-slide">卡片 4</div>
        <div class="swiper-slide">卡片 5</div>
        <div class="swiper-slide">卡片 6</div>
        <div class="swiper-slide">卡片 7</div>
        <div class="swiper-slide">卡片 8</div>
        <div class="swiper-slide">卡片 9</div>
        <div class="swiper-slide">卡片 10</div>
        <div class="swiper-slide">卡片 11</div>
        <div class="swiper-slide">卡片 12</div>
      </div>
      <div class="swiper-pagination"></div>
    </div>
  </div>

  <!-- 引入 Swiper 脚本 -->
  <script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js"></script>
  <script>
    const swiper = new Swiper('.mySwiper', {
      slidesPerView: 3,
      grid: {
        rows: 2,
        fill: 'row',
      },
      spaceBetween: 16,
      pagination: {
        el: '.swiper-pagination',
        clickable: true,
      },
    });
  </script>
</body>
</html>

总结

实现 Swiper.js 多行多列卡片滑动并不繁琐，只要牢记三个核心点：

• 模块与配置：在 Modern Swiper 中通过 modules: [Grid] 引入网格支持，并通过 slidesPerView 与 grid.rows 控制每屏容纳的行列数量；
• 样式关键：确保外层 .swiper 拥有明确的固定高度，为网格行高计算提供基准数值；
• 使用边界：将 grid.fill 设为 'row' 以保持符合人类直觉的卡片排序，且绝不与 loop: true 混用。

按照这套规范配置，既能确保卡片在多端自适应缩放时整齐划一，也能避免初学者常见的卡片坍塌与滑动错位问题。