怎么配置 wow.js 让滚动动画只播放一次

一、准备工作与基础协作关系

在调整配置之前，需要先厘清 wow.js 的工作方式。wow.js 本身并不包含动画的关键帧代码，它本质上是一个视口检测调度器。页面中具体的淡入、滑动、放大等视觉效果，由外部的 CSS 动画库（通常为 Animate.css）提供。

整个协作流程为：wow.js 监听浏览器滚动，计算目标元素相对视口顶部的位置；当元素达到触发偏移量时，wow.js 为该元素追加指定的 CSS 类名（默认为 animated 以及具体的动画名称如 fadeInUp）；随后浏览器根据 CSS 关键帧渲染动画。因此，要让动画“只播一次”，需要从脚本层的监听策略与 DOM 层的类名生命周期两个维度共同确保。

二、核心操作：JavaScript 初始化参数配置

实现单次播放的最关键环节是实例化 WOW 对象时的参数定义。请在页面底部或主脚本文件中使用以下配置：

// 创建自定义配置的 WOW 实例
var wow = new WOW({
    boxClass: 'wow',              // 需要执行动画的元素类名，默认为 'wow'
    animateClass: 'animated',      // 触发动画时追加的基础类名，默认为 'animated'
    offset: 60,                   // 距离视口底部多少像素时开始触发，默认为 0
    mobile: true,                 // 是否在移动端设备上正常触发，默认为 true
    live: false,                  // 关闭对异步加载 DOM 的持续监听，减少无谓重扫
    resetAnimation: false         // 【核心】动画播放完毕后不清除类名，锁定终态
});

// 执行初始化
wow.init();

在这段配置中，决定动画是否只播放一次的两个核心选项是 resetAnimation 与 live：

• resetAnimation: false（必须设置）：该选项直接指示 wow.js 在底层接收到浏览器的 animationend 事件时，不要执行清除 animateClass 的回调函数。类名保留后，元素的 CSS 样式将停留在最终帧。
• live: false（推荐设置）：默认情况下 live 为 true，wow.js 会创建一个 MutationObserver 监听整个文档的 DOM 结构变动。当页面存在异步数据加载、弹窗渲染或局部刷新时，live: true 会重新检索页面中的 .wow 元素。将其显式设置为 false，可以彻底关闭这层自动扫描机制，杜绝动态内容插入引发的二次触发。

三、关键机制对比：resetAnimation 为 true 与 false 的差异

许多开发者困惑于为什么有时候没有特别配置，动画看起来也只播一次，而在某些页面中往回滚动或局部更新时动画却会重新播放。这背后的核心差异正是 resetAnimation 在动画结束阶段的处理逻辑。

四、HTML 节点配置与 CSS 动画次数控制

除了全局 JavaScript 配置外，HTML 结构与节点属性的声明同样直接影响动画的播放次数。如果全局 JS 参数已正确锁定，但 HTML 标签或 CSS 规则被意外设置成了循环动画，页面依然会出现反复抖动。

1. HTML 节点属性规范

在页面 HTML 标签中，通过 data-wow-iteration 属性可以明确声明当前元素的动画播放轮次。为确保绝对只播放一次，建议对关键元素声明为 1：

<!-- 标准单次播放节点结构 -->
<div class="wow fadeInUp"
     data-wow-duration="1s"
     data-wow-delay="0.2s"
     data-wow-offset="50"
     data-wow-iteration="1">
    <h3>产品核心优势</h3>
    <p>该区域在页面滚动到达时仅执行一次平滑上浮渐现。</p>
</div>

data-wow-iteration="1" 会被 wow.js 解析并转化为内联 CSS 属性 animation-iteration-count: 1;。它能够有效覆盖某些第三方样式表中误加的全局循环规则。切勿在此处写入 infinite。

2. CSS animation-fill-mode 保障

在引入第三方动画库时，请确保 .animated 基础类中包含 animation-fill-mode: both; 或 forwards;。这一规则的作用在于：当动画完成后，元素会保留在最后一帧的视觉状态（例如 opacity: 1、偏移归位），而不是瞬间回退到动画开始前的透明或隐藏状态。Animate.css 官方版本默认已包含该规则，但如果是团队自写动画，务必自行补齐。

五、结果验证与调试确认方法

完成配置后，请按照以下步骤在实际浏览器环境中进行校验，确认动画只播放一次且没有任何异常回退：

1. 往复滚动验证：刷新页面后，平缓向下滚动页面，观察目标模块是否如期淡入或上浮。动画执行完毕后，快速或慢速向上滚动至页面顶部，然后再滚动回目标模块位置。此时元素应当完全静止，不发生任何重新位移或闪烁。
2. DevTools 类名检查：按 F12 打开浏览器开发者工具，切换到 Elements（元素）面板。在页面尚未滚动到目标元素前，该元素仅有 class="wow fadeInUp" 且带有内联样式 visibility: hidden;。当滚动到目标元素时，该类名变为 class="wow fadeInUp animated"；在动画播放结束数秒后再次观察，该类名必须依然完整保留，且内联样式维持 visibility: visible;。
3. 控制台无重复实例化警告：在 Console 面板中确认没有多次打印 WOW 初始化日志，确保整个页面生命周期仅执行了一次 wow.init()。

六、常见问题排查与注意事项

在实际项目集成中，即便设置了 resetAnimation: false，有时仍会由于外部环境干扰出现“意外重播”或“元素消失”的情况。以下是三个最直接相关的高频问题与解决办法：