怎么在 Vue 和 React 项目中正确集成 AOS.js

图 0：AOS.js 结合现代前端工程化生态的核心实践框架

AOS.js（Animate On Scroll）是一个基于视口滚动触发 CSS 过渡动画的轻量级 JavaScript 库。在传统的静态页面中，通常只要在页面底部通过脚本标签调用 AOS.init() 就能正常工作。然而在基于虚拟 DOM 与单页应用（SPA）机制构建的 Vue 或 React 项目中，开发者经常会遇到动画没有效果、首屏加载后不触发、路由跳转后动画失效，或者异步数据获取后动画错位等现象。正确集成的核心解决路径在于：在真实 DOM 节点挂载完成后的生命周期钩子中进行初始化，确保动画核心样式表被全局引入，并在路由切换或动态数据渲染引起 DOM 重排时及时调用 AOS.refresh()。本文将具体讲解在 Vue 和 React 项目中的标准实现步骤与注意事项。

一、AOS.js 核心依赖与全局样式引入

AOS.js 的运作依赖两个核心部分：负责监听滚动并计算视口交叉状态的 JavaScript 运行时脚本，以及定义具体动效过渡的 CSS 样式表（包含 data-aos 预设动画如 fade-up、zoom-in 等及其关键帧规则）。因此，规范集成的起点是正确安装包并引入样式。

在项目根目录运行安装命令：

# 使用 npm
npm install aos --save

# 使用 pnpm 或 yarn
pnpm add aos
# yarn add aos

安装完成后，必须将样式文件 aos/dist/aos.css 导入项目的全局入口文件中。如果仅在脚本中调用了 AOS.init() 而没有引入该样式表，AOS 虽能正常向 DOM 节点添加 aos-animate 类名，但由于缺失对应的 CSS 过渡与位移属性，页面上的元素不会产生任何可视动画效果。

图 1：AOS.js 规范化集成四步工作流

二、在 Vue 项目中的正确集成方案

Vue 采用响应式系统与虚拟 DOM 机制。如果在模板渲染前过早执行初始化，AOS.js 无法在当前 DOM 树中找到带有 data-aos 属性的目标元素，导致动画初始化落空。因此必须严格将初始化限定在组件挂载完成之后。

1. Vue 3 组合式 API（<script setup>）集成

在全局入口文件（如 main.js 或 main.ts）中导入样式，并在顶层根组件（如 App.vue）或通用布局组件的 onMounted 钩子中执行 AOS.init()：

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

// 必须全局引入 AOS 样式表
import 'aos/dist/aos.css'

const app = createApp(App)
app.use(router)
app.mount('#app')

在根组件 App.vue 中进行全局初始化配置：

<!-- App.vue -->
<template>
  <router-view />
</template>

<script setup>
import { onMounted } from 'vue'
import AOS from 'aos'

onMounted(() => {
  AOS.init({
    duration: 800,     // 动画持续时间（毫秒）
    easing: 'ease-out', // 缓动曲线
    once: true,         // 是否仅在首次进入视口时执行一次动画
    offset: 120         // 距离视口底部的触发偏移量（像素）
  })
})
</script>

2. 单页路由切换（Vue Router）与异步数据刷新

单页应用切换路由时，页面并没有重新加载，而是由 Vue 动态挂载新视图对应的 DOM 节点。AOS.js 内部缓存的元素高度与位置数据依然停留在上一路由页面。如果不主动通知 AOS，新页面的滚动动画往往完全失效。解决办法是在路由守卫或组件激活时调用 AOS.refresh()：

// router/index.js
import { createRouter, createWebHistory } from 'vue-router'
import { nextTick } from 'vue'
import AOS from 'aos'

const router = createRouter({
  history: createWebHistory(),
  routes: [ /* 路由配置 */ ]
})

router.afterEach(() => {
  // 等待 Vue 完成新页面的 DOM 挂载后再刷新坐标
  nextTick(() => {
    AOS.refresh()
  })
})

export default router

图 2：Vue 与 React 渲染生命周期集成对比

三、在 React 项目中的正确集成方案

在 React 函数式组件中，组件函数在每次渲染（Render 阶段）都会执行。直接在组件函数体内调用 AOS.init() 会导致每次重渲染都反复重复初始化，造成不必要的开销与滚动监听器冗余。正确的做法是将初始化放置在 useEffect 钩子内，并传入空依赖项数组 []。

1. 根组件与样式引入

在入口文件（如 main.jsx、index.jsx 或 App.jsx）中导入样式文件：

// main.jsx 或 index.js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'

// 全局导入 AOS 基础样式
import 'aos/dist/aos.css'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

2. 在 App.jsx 中执行初始化

// App.jsx
import React, { useEffect } from 'react'
import AOS from 'aos'

export default function App() {
  useEffect(() => {
    AOS.init({
      duration: 1000,
      easing: 'ease-in-out',
      once: false,
      mirror: false
    })
  }, []) // 空数组确保仅在组件初次挂载后执行一次

  return (
    <main>
      <section data-aos="fade-up">
        <h1>欢迎访问</h1>
      </section>
      <section data-aos="zoom-in" data-aos-delay="200">
        <p>这是一个带延迟缩放动效的内容块</p>
      </section>
    </main>
  )
}

3. React Router 路由跳转时的坐标同步

使用 react-router-dom 时，可以通过 useLocation 监听路径变化，在路径改变且页面完成 DOM 替换后，触发 AOS.refresh()：

// components/AosRefresher.jsx
import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
import AOS from 'aos'

export default function AosRefresher() {
  const { pathname } = useLocation()

  useEffect(() => {
    // 路由改变后刷新 AOS 元素坐标缓存
    AOS.refresh()
  }, [pathname])

  return null
}

将 <AosRefresher /> 放置在 <BrowserRouter> 内的顶层，即可自动对整个单页应用中的所有页面跳转生效。

useEffect(() => {
  import('aos').then((AOS) => {
    AOS.init({ duration: 800 })
  })
}, [])

四、AOS.js 滚动计算与动画触发原理解析

理解 AOS.js 的底层工作原理有助于快速定位各种疑难杂症。在执行 AOS.init() 时，库主要完成了三件事：

• 元素索引：通过 document.querySelectorAll('[data-aos]') 抓取当前页面所有声明了 data-aos 属性的 DOM 节点。
• 坐标缓存：计算每个节点相对于文档根部的实际垂直距离（offsetTop），并保存在内存数组中。
• 事件监听：给浏览器视口绑定经过节流（throttle/debounce）处理的滚动事件（scroll）与窗口调整事件（resize）。

当用户向下滚动页面时，AOS 引擎会计算当前视口底部位置：window.scrollY + window.innerHeight - offset。一旦该数值大于或等于某个元素的 offsetTop，说明该元素已经进入可见区域，AOS 立即为其添加 aos-animate 类名，激活 CSS 中预设的硬件加速变形或透明度过渡。

图 3：AOS.js 视口计算与类名切换原理解析

正是由于 AOS 依赖初始位置缓存，如果在初始计算之后，由于异步接口拉取数据、图片延迟加载或路由切换导致文档高度发生了改变，旧的 offsetTop 就会与真实位置产生脱节。这正是必须主动调用 AOS.refresh() 的根本原因。

五、常用配置选项与常用 HTML 属性对照

AOS 提供了两层配置机制：在 AOS.init() 中设置的全局默认值，以及直接写在具体 DOM 节点上的行内属性配置（行内属性优先级高于全局默认配置）。

六、常见问题排查与关键区别

在工程实践中，开发者常会遇到几种典型现象，以下是针对性的诊断与处理原则：

图 4：单页应用集成 AOS.js 故障排查与对策决策树

1. AOS.refresh() 与 AOS.refreshHard() 的具体区别

AOS 提供了两个刷新方法，其适用边界截然不同：

• AOS.refresh()：仅重新计算已存在元素在当前页面中的 offsetTop。适用于容器尺寸改变、字体加载后文本折行撑开高度，或者路由页面切换等情况。执行速度快，开销极小。
• AOS.refreshHard()：不仅重新计算坐标，还会重新执行 document.querySelectorAll('[data-aos]')，全面扫描并收集页面中新插入的 DOM 节点。当你在 Vue 中通过 v-if 切换显示块，或者在 React 中根据后端接口响应动态渲染了全新的包含 data-aos 属性的 DOM 节点时，必须调用 AOS.refreshHard()，否则新节点根本不会被 AOS 纳入监听名单。

2. 图片未加载完成导致的位置偏离

如果页面中包含大量未指定固定宽高比例的 <img>，在图片加载完成瞬间会突然把下方的 DOM 节点往下顶推数十至数百像素。此时之前缓存的 offsetTop 将严重失准，导致用户向下滚动很久之后元素才突然弹出。解决此问题的最佳实践是：要么为图片外层包裹设置显式纵横比（如 CSS aspect-ratio），要么在关键大图的 onload 回调中调用 AOS.refresh()。

3. 元素隐藏时的不可见陷阱

被 data-aos 作用的节点在初始化后默认会被赋予 opacity: 0。如果页面因为某种逻辑导致 AOS 没有正常触发，该元素可能会长期隐形于页面之中。排查时可临时在控制台观察该元素是否具备 aos-init 类名；若有 aos-init 但迟迟未添加 aos-animate，重点核对触发线偏移量与滚动容器是否为全局 window。