如何在WordPress中用自定义PHP短代码实现滚动触发图文动画

实现该效果一共分为三步：后端注册短代码拉取自定义字段数据、前端写布局样式、JS实现滚动触发动画逻辑，全程不需要额外第三方插件。 #

1. 注册自定义短代码（PHP代码插入到当前主题functions.php文件末尾） #

以下代码默认适配ACF插件的重复器字段，字段名设置为scroll_slides，包含两个子字段：slide_img（图片类型）、slide_text（文本/富文本类型）。如果用WordPress原生自定义字段，修改对应取值逻辑即可。

add_shortcode('scroll_slide_animation', function($atts) {
    // 只有在单篇/页面生效
    if (!is_singular()) return '';
    global $post;
    // 从自定义字段拉取所有图文组
    $slides = get_field('scroll_slides', $post->ID);
    if (empty($slides)) return '';
    ob_start();
    ?>
    <div class="scroll-slide-wrapper">
        <div class="slide-imgs-group">
            <?php foreach ($slides as $index => $slide) : ?>
            <div class="slide-img-item <?php echo $index === 0 ? 'active' : ''; ?>" data-index="<?php echo $index; ?>">
                <?php echo wp_get_attachment_image($slide['slide_img']['ID'], 'full'); ?>
            </div>
            <?php endforeach; ?>
        </div>
        <div class="slide-texts-group">
            <?php foreach ($slides as $index => $slide) : ?>
            <div class="slide-text-item <?php echo $index === 0 ? 'active' : ''; ?>" data-index="<?php echo $index; ?>">
                <?php echo wp_kses_post($slide['slide_text']); ?>
            </div>
            <?php endforeach; ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
});

短代码注册完成后，在需要展示的页面/文章中插入[scroll_slide_animation]即可调用该模块。 #

2. 布局样式（CSS代码插入到主题「自定义-额外CSS」中） #

.scroll-slide-wrapper {
    display: flex;
    align-items: center;
    gap: 40px;
    min-height: 600px;
    position: relative;
    overflow: hidden;
    margin: 60px 0;
}
.slide-imgs-group {
    width: 50%;
    position: relative;
    height: 500px;
}
.slide-img-item {
    position: absolute;
    top: -100%;
    left: 0;
    width: 100%;
    height: 100%;
    transition: top 0.6s ease;
}
.slide-img-item img {
    width: 100%;
    height: 100%;
    object-fit: cover;
}
.slide-img-item.active {
    top: 0;
}
.slide-texts-group {
    width: 45%;
    position: relative;
    min-height: 300px;
}
.slide-text-item {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    opacity: 0;
    visibility: hidden;
    transition: all 0.4s ease;
}
.slide-text-item.active {
    opacity: 1;
    visibility: visible;
}
/* 动画期间禁用全局滚动 */
body.disable-scroll {
    overflow: hidden;
    height: 100vh;
}

可以根据自己的设计需求调整尺寸、间距、动画过渡时长参数。 #

3. 滚动交互逻辑（JS代码插入到主题footer.php文件wp_footer()函数之前） #

document.addEventListener('DOMContentLoaded', function() {
    const wrapper = document.querySelector('.scroll-slide-wrapper');
    if (!wrapper) return;
    const imgItems = wrapper.querySelectorAll('.slide-img-item');
    const textItems = wrapper.querySelectorAll('.slide-text-item');
    const totalSlides = imgItems.length;
    let currentIndex = 0;
    let isAnimating = false;
    // 监听滚动事件
    window.addEventListener('wheel', function(e) {
        // 动画中、已经到最后一张都不触发
        if (isAnimating || currentIndex >= totalSlides - 1) return;
        // 只有向下滚动触发
        if (e.deltaY < 0) return;
        e.preventDefault();
        // 禁用全局滚动
        document.body.classList.add('disable-scroll');
        isAnimating = true;
        // 切换到下一张
        const nextIndex = currentIndex + 1;
        // 新图片下滑进入
        imgItems[nextIndex].classList.add('active');
        // 旧文字隐藏
        textItems[currentIndex].classList.remove('active');
        // 等待动画完成
        setTimeout(function() {
            // 新文字显示
            textItems[nextIndex].classList.add('active');
            currentIndex = nextIndex;
            isAnimating = false;
            // 恢复全局滚动
            document.body.classList.remove('disable-scroll');
        }, 600); // 和CSS里的图片动画时长保持一致
    }, { passive: false });
});

如果需要适配移动端触摸滑动，额外加触摸事件监听即可，逻辑和滚轮事件一致。 #

内容的提问来源于stack exchange，提问作者Damian Kursa