如何正确添加 Splide Grid 扩展插件

霞舞 2026-01-21 00:00:00 次阅读

splide grid 扩展需通过 `window.splide.extensions` 而非 `window.splide.grid` 挂载，且必须确保 grid 插件脚本已正确加载、配置项结构符合 v4+ 规范（如使用 `rows/cols` 替代旧版 `dimensions`）。

在 Splide v4 及更高版本中，Grid 扩展的挂载方式

已发生重要变更：不再支持直接挂载 window.splide.Grid，而必须统一通过 window.splide.Extensions 对象注册所有官方扩展。这是导致你代码中 Grid 未生效的根本原因。

✅ 正确集成步骤

引入必要资源（按顺序）：

初始化时挂载 Extensions（关键！）：

jQuery(function($) {
  const splide = new Splide('#exmpale-slick', {
    type: 'loop',
    height: '20rem',
    gap: '1em',
    perPage: 2,
    perMove: 1,
    // ✅ Grid 配置：v4+ 推荐使用 rows/cols + gap（更语义化）
    grid: {
      rows: 2,
      cols: 2,
      gap: {
        row: '1em',
        col: '1em'
      }
    },
    breakpoints: {
      600: {
        height: '10rem',
        perPage: 1,
        grid: {
          rows: 1,
          cols: 1,
          gap: {
            row: '.5em',
            col: '.5em'
          }
        }
      }
    }
  });

  // ✅ 正确挂载方式：传入 window.splide.Extensions
  splide.mount(window.splide.Extensions);
});

⚠️ 注意事项

dimensions 已弃用：旧文档中使用的 dimensions: [[2, 0.5], [2, 2], ...] 是 v3 语法，v4+ 中已被 rows / cols 取代。混合使用会导致 Grid 不渲染。
HTML 结构无需额外 class：Splide Grid 会自动为 .splide__slide 元素添加网格布局样式（display: grid 等），请确保 .splide__list 下直接是
，你的 HTML 符合要求。
避免重复引入或 CDN 版本不匹配：检查浏览器控制台是否报错 Splide is not defined 或 Grid is not a constructor —— 这通常意味着 splide-extension-grid.min.js 加载失败或版本与 Splide 主库不兼容（推荐使用 CDNJS 或 jsDelivr 的明确版本号）。

jQuery 非必需：若项目无其他 jQuery 依赖，建议改用原生写法，避免潜在冲突：

document.addEventListener('DOMContentLoaded', () => {
  const splide = new Splide('#exmpale-slick', { /* config */ });
  splide.mount(window.splide.Extensions);
});