如何在 Splide 中正确启用 Grid 扩展

本文详解 splide grid 扩展的集成方法，重点纠正 `mount()` 时误用 `window.splide.grid` 导致扩展失效的问题，明确应使用 `window.splide.extensions` 并配合正确的配置项（如 `rows`/`cols` 替代已废弃的 `dimensions`），确保网格布局正常渲染。

Splide 的 Grid 扩展用于在单个幻灯片内构建多行多列的嵌套网格布局（例如：一张“幻灯片”显示 2×2 的子卡片），但其启用方式极易出错——最常见错误是调用 .mount(window.splide.Grid)。该写法在新版 Splide（v4+）中已无效，因为 Grid 不再作为独立挂载模块存在，而是被统一纳入 Extensions 集合中。

✅ 正确做法是：

1. 确保加载顺序正确：先引入 splide.min.js（核心库），再引入 @splidejs/splide-extension-grid（Grid 扩展）；
2. 通过 CDN 加载时，推荐使用 ESM 方式（现代浏览器）或 UMD 构建版本；
3. 挂载时必须使用 window.splide.Extensions（而非 window.splide.Grid）；
4. Grid 配置需使用 rows 和 cols 字段（注意：文档中旧版 dimensions 数组语法在 v4+ 已弃用，不再生效）。

以下是可直接运行的完整示例代码：

Pebblely

AI产品图精美背景添加

下载

  

    

      
Slide 1
      
Slide 2
      
Slide 3
      
Slide 4
    
  

// 初始化并挂载 Grid 扩展
document.addEventListener('DOMContentLoaded', () => {
  const splide = new Splide('#example-splide', {
    type: 'loop',
    perPage: 1,
    grid: {
      rows: 2,     // 网格行数（每张幻灯片内）
      cols: 2,     // 网格列数
      gap: {
        row: '1rem',
        col: '1rem'
      }
    },
    breakpoints: {
      768: {
        grid: {
          rows: 1,
          cols: 2,
          gap: { row: '0.5rem', col: '0.5rem' }
        }
      }
    }
  });

  // ✅ 关键：挂载 Extensions 对象，不是 Grid 单独对象
  splide.mount(window.splide.Extensions);
});

⚠️ 注意事项：

• 若使用
• grid 配置仅对 type: 'slide' 或 type: 'loop' 有效，type: 'fade' 等不支持；
• 每个 .splide__slide 元素将被自动拆分为 rows × cols 个单元格（即内部再分页），因此需确保子内容结构语义清晰；
• 响应式 breakpoints 中的 grid 配置会完全覆盖默认值，无需重复声明未变更字段。

总结：Grid 扩展不是“插件式挂载”，而是 Splide 内置扩展体系的一部分。牢记 mount(window.splide.Extensions) 这一标准入口，并采用 rows/cols 配置语法，即可稳定启用网格布局功能。