WordPress 引入 GSAP：解决 Elementor 与主题动画冲突

在 WordPress 引入 GSAP 后，如果动画被 Elementor 或主题的 CSS 过渡覆盖，可以从脚本加载顺序、元素选择器和 transition 三个方向排查。下面记录两种加载方式，以及只针对目标元素处理 GSAP 动画冲突的方法。

方法一：使用 WordPress 正确加载 GSAP

先从 GSAP 官网确认当前可用版本。对于长期维护的网站，优先使用子主题或自定义插件中的 wp_enqueue_script()，让 WordPress 管理依赖和加载顺序；不熟悉代码时也可以使用 WPCode，但要避免同一库被主题和代码片段重复加载。

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'gsap',
        'https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js',
        array(),
        null,
        true
    );

    wp_enqueue_script(
        'site-gsap-animation',
        get_stylesheet_directory_uri() . '/assets/js/site-gsap.js',
        array( 'gsap' ),
        '1.0.0',
        true
    );
} );

如果使用 WPCode，可以把 GSAP 库放在自定义动画代码之前，并尽量加载到页脚。保存后在浏览器控制台输入 typeof gsap，返回 object 通常说明库已加载。

为什么 Elementor 或主题动画会冲突

GSAP 会持续写入元素的 transform、opacity 等属性，而主题或 Elementor 可能同时对这些属性设置 CSS transition。两套动画系统作用于同一属性时，CSS 过渡会再次插值，表现为延迟、拖尾、抖动或无法到达预期位置。

只对目标元素关闭 CSS transition

例如目标容器 ID 为 s1，可以仅关闭这个容器及确实由 GSAP 控制元素的过渡：

#s1 {
    transition: none !important;
}

不建议使用全局 * { transition: none !important; }，因为它会同时破坏按钮、菜单、弹窗和其他组件的正常动画。若冲突发生在子元素，应给该子元素单独添加 class，再精确覆盖。

一个最小动画示例

document.addEventListener('DOMContentLoaded', function () {
    const target = document.querySelector('#s1');
    if (!target || typeof gsap === 'undefined') return;

    gsap.fromTo(
        target,
        { autoAlpha: 0, y: 32 },
        { autoAlpha: 1, y: 0, duration: 0.8, ease: 'power2.out' }
    );
});

判断元素是否存在，可以避免某些页面没有该容器时出现 JavaScript 错误。使用 autoAlpha 会同时处理 opacity 和 visibility，适合入场动画。

排查清单

• 页面是否只加载了一份 GSAP，版本是否一致。
• 自定义动画代码是否在 GSAP 加载完成后执行。
• 选择器是否唯一，Elementor 复制容器后是否产生重复 ID。
• 主题是否给 transform、opacity 或 all 设置了 transition。
• 缓存和代码合并功能是否改变了脚本顺序；修改后需清理页面、CDN 和浏览器缓存。
• 动画元素是否在弹窗、Tab 或延迟渲染组件内；这类元素可能需要在组件显示后再初始化。

总结

WordPress 中的 GSAP 动画冲突通常不需要全局禁用主题动画。确保 GSAP 先加载、动画代码后执行，并只在目标元素上移除冲突的 CSS transition，既能让 GSAP 正常控制属性，也不会破坏站点其他交互效果。