用 Elementor Loop Item + 本地 Swiper 实现可自定义的上下滚动文章列表

在很多 WordPress 项目中，我们都希望列表展示既美观又灵活，还能让设计师在后台直接调整样式。Elementor Loop Builder 可以帮我们灵活定制每一条内容的布局，但在实际项目中，想要结合前端的滚动效果（比如 Swiper 的上下轮播）时，就需要一些额外的开发。

这篇文章记录了一个从需求到落地的完整过程，希望能帮到有类似场景的你。

背景需求

用户需求很明确：

使用 Elementor Loop Item 来控制单个内容卡片的结构和样式，后台可视化修改。
使用 Swiper.js 实现列表的上下滚动效果。
Swiper 资源要本地引入，不走 CDN。
用 短代码 调用，传参可指定文章类型、文章数量、模板 ID，方便不同页面灵活调用。

遇到的问题

Elementor 的模板调用方法 \Elementor\Plugin::instance()->frontend->get_builder_content_for_display() 默认不会输出内联 CSS，导致样式缺失。
网上常见的调用方式直接输出结构，没有包含 Loop Item 中的 CSS。
用 the_post() 时，已经完成了 $post 的初始化，如果再手动 setup_postdata() 会多此一举。

解决步骤

1. 确定模板调用方法

Elementor 官方方法：

get_builder_content_for_display($template_id, true)

第二个参数传 true，就会连同内联 CSS 一起输出，这样 Loop Item 样式就能正常生效。

2. 设计插件结构

目录结构：

hzt-loop-swiper/
│
├─ hzt-loop-swiper.php
├─ assets/

这样可以把 Swiper 资源本地化，避免外部依赖。

3. 编写插件代码

核心逻辑：

注册短代码 [hzt_loop_swiper]
接收参数 post_type、posts_per_page、template_id
循环查询文章，每条用 Loop Item 渲染
本地引入 Swiper CSS/JS，并初始化纵向轮播

代码示例：

<?php
/*
Plugin Name: HZT Loop Swiper
Description: 使用 Elementor Loop Item + 本地 Swiper 制作上下滚动效果
Version: 1.0
Author: 你的名字
*/

if (!defined('ABSPATH')) exit;

class HZT_Loop_Swiper {
    public function __construct() {
        add_shortcode('hzt_loop_swiper', [$this, 'shortcode_render']);
        add_action('wp_enqueue_scripts', [$this, 'register_assets']);
    }

    public function register_assets() {
        $plugin_url = plugin_dir_url(__FILE__);
        wp_register_style('hzt-swiper', $plugin_url . 'assets/swiper-bundle.min.css', [], '9.0.0');
        wp_register_script('hzt-swiper', $plugin_url . 'assets/swiper-bundle.min.js', [], '9.0.0', true);
    }

    public function shortcode_render($atts) {
        $atts = shortcode_atts([
            'post_type'      => 'post',
            'posts_per_page' => 5,
            'template_id'    => 0,
        ], $atts, 'hzt_loop_swiper');

        if (empty($atts['template_id'])) {
            return '<p>❌ 请传入 template_id 参数</p>';
        }

        wp_enqueue_style('hzt-swiper');
        wp_enqueue_script('hzt-swiper');

        $query = new WP_Query([
            'post_type'      => sanitize_text_field($atts['post_type']),
            'posts_per_page' => intval($atts['posts_per_page']),
            'post_status'    => 'publish',
        ]);

        ob_start();

        if ($query->have_posts()) :
        ?>
            <div class="swiper my-loop-swiper">
                <div class="swiper-wrapper">
                    <?php while ($query->have_posts()): $query->the_post(); ?>
                        <div class="swiper-slide">
                            <?php
                            echo \Elementor\Plugin::instance()->frontend->get_builder_content_for_display(
                                intval($atts['template_id']),
                                true
                            );
                            ?>
                        </div>
                    <?php endwhile; ?>
                </div>
            </div>

            <script>
            document.addEventListener('DOMContentLoaded', function () {
                new Swiper('.my-loop-swiper', {
                    direction: 'vertical',
                    loop: true,
                    slidesPerView: 3,
                    autoplay: {
                        delay: 3000,
                        disableOnInteraction: false,
                    },
                });
            });
            </script>
        <?php
        endif;

        wp_reset_postdata();
        return ob_get_clean();
    }
}

new HZT_Loop_Swiper();

4. 使用方法

在任何文章或页面插入短代码：

[hzt_loop_swiper post_type="product" posts_per_page="6" template_id="364"]

post_type → 文章类型（如 product）
posts_per_page → 显示的条数
template_id → Elementor Loop Item 模板 ID

效果与优势

样式完全由 Elementor 后台模板控制，前端无需改结构。
Swiper 本地加载，性能和稳定性更好。
短代码参数灵活，不同页面可调用不同模板和数据。
纵向滚动、自动播放都可以随时在初始化脚本中修改。

附件下载：hzt-elementor-loop-swiper 百度网盘下载
链接: https://pan.baidu.com/s/1_g8xU6UQWMh5Hzff7T5Etg 提取码: fs94

使用方法

在elementor中插入短代码
[hzt_loop_swiper post_type=”product” posts_per_page=”10″ max_height=”480px” template_id=”373″]
loop id 为elementor 的 loop item id 查看方法如下