jQuery + Swiper.js 实现动态渲染轮播图

前言

在前端开发中，Banner 轮播图是项目里非常常见的模块。很多新手直接在页面写死 swiper-slide，但是实际项目中轮播图图片一般是后端接口返回，需要JS 动态拼接 DOM 字符串渲染，再初始化 Swiper 实例。本文基于 Swiper 原生 API+jQuery 实现，把接口返回的图片数组循环拼接 html，渲染完成后实例化 Swiper，实现自动轮播、分页圆点、循环播放。同时会讲解代码坑点，比如重复实例化 Swiper 导致轮播失效问题。

技术栈：Swiper + jQuery，适合传统多页面项目、后台管理、H5 活动页。

完整代码示例

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Swiper动态渲染轮播图</title>
    <!-- 引入Swiper css -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.css"/>
    <style>
        .swiper{
            width: 100%;
            height: 220px;
        }
        .swiper-slide img{
            width:100%;
            height:100%;
            object-fit: cover;
        }
    </style>
</head>
<body>
    <!-- swiper基础DOM结构 -->
    <div class="swiper">
        <div class="swiper-wrapper">
            <!-- 这里的swiper-slide由JS动态渲染 -->
        </div>
        <!-- 分页圆点容器 -->
        <div class="swiper-pagination"></div>
    </div>

    <!-- jQuery 和 Swiper js -->
    <script src="https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.js"></script>
    <script>
        // 模拟后端返回的轮播图数据，真实项目替换为ajax接口返回结果
        const bannerData = [
            {img:"https://picsum.photos/id/1/800/300"},
            {img:"https://picsum.photos/id/2/800/300"},
            {img:"https://picsum.photos/id/3/800/300"},
        ]

        //轮播图渲染
        function render_banner(data) {
            let banner_pic_data = ''
            for (let i = 0; i < data.length; i++) {
                if (i == data.length) {
                    break;
                }
                banner_pic_data += `
                    <div class="swiper-slide">
                        <img src="${data[i].img}" alt="">
                    </div>
                `
            }
            $('.swiper-wrapper').html(banner_pic_data);
            banner_pic_swiper();
        }

        // 轮播图配置
        function banner_pic_swiper() {
            var mySwiper = new Swiper('.swiper', {
                // 循环播放
                loop: true,
                // 分页器效果
                pagination: {
                    el: '.swiper-pagination',
                    clickable: true,
                    type: 'bullets', // 使用 bullet 类型（可自定义）
                    dynamicBullets: false, // 关闭动态子弹
                    bulletClass: 'swiper-pagination-bullet', // 自定义类名
                    bulletActiveClass: 'swiper-pagination-bullet-active'
                },
                // 自动切换
                autoplay: {
                    delay: 2000,
                    stopOnLastSlide: false,
                    disableOnInteraction: false,
                },
                // 其他配置
                slidesPerView: 'auto',
                slidesPerGroupAuto: true,
            });
        }

        //页面加载完成调用渲染函数，真实场景放在ajax成功回调里面
        $(function(){
            render_banner(bannerData);
        })
    </script>
</body>
</html>

代码逐段解析

1、DOM 结构说明

Swiper 的固定结构：.swiper 外层容器 → .swiper-wrapper 滑块容器 → .swiper-slide 每一张轮播图。 .swiper-pagination 是分页圆点容器，不要用 JS 动态删除这个节点，Swiper 实例会自动在这里生成圆点。

关键点：swiper-slide 不是写死在页面，是 JS 循环拼接字符串，用 jQuery .html() 一次性渲染到.swiper-wrapper。

2、render_banner (data) 渲染函数

复制代码

function render_banner(data) {
    let banner_pic_data = ''
    for (let i = 0; i < data.length; i++) {
        if (i == data.length) {
            break;
        }
        banner_pic_data += `
            <div class="swiper-slide">
                <img src="${data[i].img}" alt="">
            </div>
        `
    }
    $('.swiper-wrapper').html(banner_pic_data);
    banner_pic_swiper();
}

参数data：后端接口返回的图片数组，包含图片地址字段img
循环拼接模板字符串，把每一张图片包装成swiper-slide
使用$('.swiper-wrapper').html()覆盖原有内容
渲染 DOM 完成之后，立刻初始化 Swiper 实例 ：banner_pic_swiper()

顺序不能颠倒：必须先渲染 DOM 节点，再 new Swiper。如果先实例 Swiper，此时页面还没有 slide，轮播直接失效。

3、banner_pic_swiper () Swiper 配置项详解

复制代码

var mySwiper = new Swiper('.swiper', {
    loop: true, //开启无缝循环
    pagination: {
        el: '.swiper-pagination', //绑定分页容器
        clickable: true, //圆点可以点击切换轮播
        type: 'bullets', //圆点样式，可选fraction、progressbar
        dynamicBullets: false, //关闭动态圆点大小
        bulletClass: 'swiper-pagination-bullet',
        bulletActiveClass: 'swiper-pagination-bullet-active'
    },
    autoplay: {
        delay: 2000, //自动播放间隔，单位ms，2000=2秒切换一次
        stopOnLastSlide: false, //到最后一张不停止
        disableOnInteraction: false, //用户手动滑动后，继续自动播放
    },
    slidesPerView: 'auto', //自动根据宽度显示数量
    slidesPerGroupAuto: true,
});

重点配置说明：

loop:true：无缝循环轮播，Swiper 底层会复制节点实现循环
autoplay.disableOnInteraction:false：用户手动拖动轮播之后，不会停止自动播放，很多业务需求需要这个效果。默认值 true，拖动后停止轮播。
pagination.clickable:true：分页圆点支持点击跳转轮播图。

拓展业务场景

轮播图点击跳转详情：给 slide 增加点击事件，把 id 挂载到元素上，点击获取 id 跳转页面
增加左右箭头按钮：在 swiper 配置中增加 navigation 配置
移动端 H5 banner、后台首页广告轮播、商城首页广告图

知识点总结

渲染顺序：先动态渲染 swiper-slide DOM，再实例化 Swiper，顺序不能颠倒。
实例管理：多次刷新数据，必须销毁旧 Swiper 实例，否则多个实例冲突。
disableOnInteraction：自动播放重要配置，根据业务选择手动滑动后是否继续轮播。
jQuery 模板字符串拼接 DOM，适合传统项目动态渲染列表。
增加数据容错判断，防止空数据、图片异常导致页面 JS 报错。

适用场景：传统 jQuery 项目、后端返回 Banner 图片列表，动态渲染轮播，不是静态写死图片的场景。