scroll-reveal-libraries

滚动显示库

概述

本技能介绍 AOS（滚动时动画），这是一个轻量级、由 CSS 驱动的库，用于实现滚动触发动画。AOS 擅长制作简单的淡入、滑动和缩放效果，并在元素进入视口时触发。

主要功能：

• 极简配置：单个 JavaScript 文件 + CSS
• 数据属性 API：在 HTML 中配置动画
• 性能：由 CSS 驱动，并使用 GPU 加速动画
• 50 多种内置动画：淡入、滑动、缩放、翻转
• 框架无关：适用于原生 JS、React、Vue 等

适用场景：

• 带有简单滚动效果的营销页面／落地页
• 内容丰富的网站（博客、文档）
• 需要滚动动画的快速原型
• 无需 GSAP／Framer Motion 复杂功能的项目

不适用场景：

• 复杂的动画时间线或编排 → 使用 GSAP ScrollTrigger
• 基于物理效果的动画 → 使用 React Spring 或 Framer Motion
• 精确同步滚动的动画 → 使用 GSAP ScrollTrigger
• 大量交互式动画 → 使用 Framer Motion

核心概念

安装

CDN（最快）：

<head>
  <link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
</head>
<body>
  

  <script src="https://unpkg.com/aos@next/dist/aos.js"></script>
  <script>
    AOS.init();
  </script>
</body>

NPM/Yarn（推荐）：

npm install aos@next
# or
yarn add aos@next

import AOS from 'aos';
import 'aos/dist/aos.css';

AOS.init();

基本用法

使用 data-aos 属性应用动画：

<div data-aos="fade-in">Content</div>


<div data-aos="fade-up">Content</div>


<div data-aos="slide-left">Content</div>


<div data-aos="zoom-in">Content</div>

配置选项

全局配置：

AOS.init({
  // Animation settings
  duration: 800,  // Animation duration (ms): 0-3000
  delay: 0,       // Delay before animation (ms): 0-3000
  offset: 120,    // Offset from trigger point (px)
  easing: 'ease', // Easing function
  once: false,    // Animate only once (true) or every time (false)
  mirror: false,  // Animate out when scrolling past

  // Placement
  anchorPlacement: 'top-bottom', // Which position triggers animation

  // Performance
  disable: false,                // Disable on mobile/tablet
  startEvent: 'DOMContentLoaded', // Initialization event
  debounceDelay: 50,             // Window resize debounce
  throttleDelay: 99              // Scroll throttle
});

单个元素的覆盖设置：

<div
  data-aos="fade-up"
  data-aos-duration="1000"
  data-aos-delay="200"
  data-aos-offset="50"
  data-aos-easing="ease-in-out"
  data-aos-once="true"
  data-aos-mirror="true"
  data-aos-anchor-placement="center-bottom"
>
  Custom configured element
</div>

常见模式

1. 落地页主视觉区域

<section class="hero">
  
  <h1
    data-aos="fade-down"
    data-aos-duration="800"
  >
    Welcome to the Future
  </h1>

  
  <p
    data-aos="fade-up"
    data-aos-delay="200"
    data-aos-duration="600"
  >
    Transform your ideas into reality
  </p>

  
  <button
    data-aos="zoom-in"
    data-aos-delay="400"
    data-aos-duration="500"
  >
    Get Started
  </button>
</section>

2. 功能卡片网格

<div class="features-grid">
  
  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    <h3>Feature 1</h3>
    <p>Description...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="100"
  >
    <h3>Feature 2</h3>
    <p>Description...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    <h3>Feature 3</h3>
    <p>Description...</p>
  </div>
</div>

3. 交替排列的内容区域

<div class="section">
  <div
    class="content"
    data-aos="slide-right"
    data-aos-duration="800"
  >
    <h2>Section Title</h2>
    <p>Content slides in from left...</p>
  </div>
  <img
    src="image1.jpg"
    data-aos="fade-left"
    data-aos-delay="200"
  />
</div>


<div class="section reverse">
  <img
    src="image2.jpg"
    data-aos="fade-right"
  />
  <div
    class="content"
    data-aos="slide-left"
    data-aos-duration="800"
    data-aos-delay="200"
  >
    <h2>Section Title</h2>
    <p>Content slides in from right...</p>
  </div>
</div>

4. 滚动触发的用户评价

<div class="testimonials">
  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
  >
    <blockquote>"Amazing product!"</blockquote>
    <cite>- John Doe</cite>
  </div>

  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
    data-aos-delay="100"
  >
    <blockquote>"Exceeded expectations"</blockquote>
    <cite>- Jane Smith</cite>
  </div>
</div>

5. 自定义锚点触发器

根据另一个元素的滚动位置触发动画：

<div class="main-content">
  <div id="trigger-point" data-aos-id="sidebar-trigger">
    
  </div>
</div>

<aside
  class="sidebar"
  data-aos="fade-left"
  data-aos-anchor="#trigger-point"
>
  Sidebar content
</aside>

6. 连续动画链

<div class="animation-sequence">
  
  <h2
    data-aos="fade-down"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    Our Process
  </h2>

  
  <p
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    Follow these simple steps
  </p>

  
  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="400"
  >
    Step 1
  </div>

  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="600"
  >
    Step 2
  </div>

  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="800"
  >
    Step 3
  </div>
</div>

7. 带缩放效果的图片库

<div class="gallery">
  <img
    src="photo1.jpg"
    data-aos="zoom-in-up"
    data-aos-duration="800"
  />
  <img
    src="photo2.jpg"
    data-aos="zoom-in-up"
    data-aos-duration="800"
    data-aos-delay="100"
  />
  <img
    src="photo3.jpg"
    data-aos="zoom-in-up"
    data-aos-duration="800"
    data-aos-delay="200"
  />
</div>

集成模式

React 集成

基本设置：

import { useEffect } from 'react';
import AOS from 'aos';
import 'aos/dist/aos.css';

function App() {
  useEffect(() => {
    AOS.init({
      duration: 800,
      once: true,
      offset: 100
    });
  }, []);

  return (
    <div>
      <h1 data-aos="fade-down">Welcome</h1>
      <p data-aos="fade-up">Content here</p>
    </div>
  );
}

路由变更时刷新：

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import AOS from 'aos';

function App() {
  const location = useLocation();

  useEffect(() => {
    AOS.init({ duration: 800 });
  }, []);

  // Refresh AOS on route change
  useEffect(() => {
    AOS.refresh();
  }, [location]);

  return <Routes>{/* routes */}</Routes>;
}

动态内容更新：

import { useState, useEffect } from 'react';
import AOS from 'aos';

function DynamicList() {
  const [items, setItems] = useState([]);

  useEffect(() => {
    AOS.init();
  }, []);

  const addItem = () => {
    setItems([...items, { id: Date.now(), text: 'New Item' }]);

    // Refresh AOS to detect new elements
    setTimeout(() => AOS.refresh(), 50);
  };

  return (
    <div>
      <button onClick={addItem}>Add Item</button>
      <ul>
        {items.map((item) => (
          <li key={item.id} data-aos="fade-in">
            {item.text}
          </li>
        ))}
      </ul>
    </div>
  );
}

组件包装模式：

import AOS from 'aos';
import 'aos/dist/aos.css';

function AnimatedSection({ children, animation = "fade-up", delay = 0, ...props }) {
  return (
    <div
      data-aos={animation}
      data-aos-delay={delay}
      {...props}
    >
      {children}
    </div>
  );
}

// Usage
<AnimatedSection animation="slide-right" delay={200}>
  <h2>Animated Content</h2>
</AnimatedSection>

Vue.js 集成

<template>
  <div>
    <h1 data-aos="fade-down">Vue + AOS</h1>
    <div
      v-for="(item, index) in items"
      :key="item.id"
      data-aos="fade-up"
      :data-aos-delay="index * 100"
    >
      {{ item.text }}
    </div>
  </div>
</template>

<script>
import AOS from 'aos';
import 'aos/dist/aos.css';

export default {
  mounted() {
    AOS.init({ duration: 800 });
  },
  updated() {
    // Refresh when component updates
    this.$nextTick(() => {
      AOS.refresh();
    });
  },
  data() {
    return {
      items: [/*...*/]
    };
  }
};
</script>

Next.js 集成

// pages/_app.js
import { useEffect } from 'react';
import AOS from 'aos';
import 'aos/dist/aos.css';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    AOS.init({
      duration: 800,
      once: true
    });
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

// pages/index.js
export default function Home() {
  return (
    <main>
      <h1 data-aos="fade-down">Next.js + AOS</h1>
      <p data-aos="fade-up">Server-side rendered content with animations</p>
    </main>
  );
}

性能优化

1. 在移动设备上禁用

AOS.init({
  disable: 'mobile', // Disable on mobile
  // Or use function for custom logic
  disable: function() {
    return window.innerWidth < 768;
  }
});

2. 使用 once 提升性能

AOS.init({
  once: true, // Animate only once (better performance)
  mirror: false // Don't animate out
});

3. 优化节流和防抖

AOS.init({
  throttleDelay: 99,  // Scroll event throttle (default)
  debounceDelay: 50   // Resize event debounce (default)
});

4. 对静态内容禁用 Mutation Observer

AOS.init({
  disableMutationObserver: true // Disable for fully static content
});

5. 降低动画复杂度

<div data-aos="fade-in">Simple fade</div>


<div data-aos="flip-left">Complex flip</div>

6. 使用 RequestIdleCallback 进行初始化

if ('requestIdleCallback' in window) {
  requestIdleCallback(() => {
    AOS.init({ duration: 800 });
  });
} else {
  AOS.init({ duration: 800 });
}

常见问题

1. DOM 变更后忘记刷新

问题：动态添加新元素后不会播放动画。

解决方案：调用 AOS.refresh() 或 AOS.refreshHard()：

// After adding elements to DOM
const newElement = document.createElement('div');
newElement.setAttribute('data-aos', 'fade-in');
container.appendChild(newElement);

// Refresh AOS
AOS.refresh(); // Recalculate positions
// or
AOS.refreshHard(); // Reinitialize completely

2. 动画在 React 中无法正常工作

问题：AOS 无法在首次渲染或路由变更时检测到元素。

解决方案：在 useEffect 中初始化，并在路由／内容变更时刷新：

useEffect(() => {
  AOS.init();
  return () => AOS.refresh(); // Cleanup
}, []);

useEffect(() => {
  AOS.refresh(); // Refresh on route change
}, [location.pathname]);

3. 滚动性能问题

问题：有许多动画元素时，页面滚动会感觉卡顿。

解决方案：减少动画元素，并使用 once: true：

AOS.init({
  once: true, // Animate only once
  disable: window.innerWidth < 768 // Disable on mobile
});

4. CSS 冲突

问题：自定义 CSS 会干扰 AOS 动画。

解决方案：使用更具体的选择器，并避免使用 !important：

/* Bad: Conflicts with AOS */
div {
  opacity: 1 !important;
}

/* Good: Specific selector */
.my-content > div {
  /* styles */
}

5. 锚点位置易混淆

问题：动画在意料之外的滚动位置触发。

解决方案：了解锚点位置选项：

// Triggers when element's top hits viewport bottom
data-aos-anchor-placement="top-bottom"

// Triggers when element's center hits viewport center
data-aos-anchor-placement="center-center"

// Triggers when element's bottom hits viewport top
data-aos-anchor-placement="bottom-top"

6. 时长／延迟限制

问题：超过 3000ms 的值不起作用。

解决方案：添加自定义 CSS 以延长时长：

body[data-aos-duration='4000'] [data-aos],
[data-aos][data-aos][data-aos-duration='4000'] {
  transition-duration: 4000ms;
}

<div data-aos="fade-in" data-aos-duration="4000">
  Long animation
</div>

内置动画

淡入动画

• fade-in - 简单淡入
• fade-up - 从底部淡入
• fade-down - 从顶部淡入
• fade-left - 从右侧淡入
• fade-right - 从左侧淡入
• fade-up-right - 对角线方向淡入
• fade-up-left - 对角线方向淡入
• fade-down-right - 对角线方向淡入
• fade-down-left - 对角线方向淡入

滑动动画

• slide-up - 从底部滑入
• slide-down - 从顶部滑入
• slide-left - 从右侧滑入
• slide-right - 从左侧滑入

缩放动画

• zoom-in - 放大
• zoom-in-up - 从底部放大进入
• zoom-in-down - 从顶部放大进入
• zoom-in-left - 从右侧放大进入
• zoom-in-right - 从左侧放大进入
• zoom-out - 缩小
• zoom-out-up - 向顶部缩小离开
• zoom-out-down - 向底部缩小离开
• zoom-out-left - 向左侧缩小离开
• zoom-out-right - 向右侧缩小离开

翻转动画

• flip-up - 从底部翻转进入
• flip-down - 从顶部翻转进入
• flip-left - 从右侧翻转进入
• flip-right - 从左侧翻转进入

自定义动画

使用 CSS 创建自定义动画：

[data-aos="custom-slide-bounce"] {
  opacity: 0;
  transform: translateY(100px);
  transition-property: transform, opacity;
}

[data-aos="custom-slide-bounce"].aos-animate {
  opacity: 1;
  transform: translateY(0);
  animation: bounce 0.5s;
}

@keyframes bounce {
  0%, 20%, 50%, 80%, 100% {
    transform: translateY(0);
  }
  40% {
    transform: translateY(-10px);
  }
  60% {
    transform: translateY(-5px);
  }
}

<div data-aos="custom-slide-bounce">
  Custom animation
</div>

与替代方案的对比

AOS 与 GSAP ScrollTrigger

特性	AOS	GSAP ScrollTrigger
复杂度	简单，基于数据属性	高级，使用 JavaScript API
使用场景	简单的显现效果	复杂的时间线
文件大小	~13KB	~27KB（GSAP）+ ScrollTrigger
性能	CSS 驱动	JavaScript 驱动
学习曲线	几分钟	几小时
自定义能力	有限	丰富
最适合	营销页面	交互式体验

在以下情况下使用 AOS：

• 简单的淡入／滑动／缩放效果
• 需要快速实现
• 倾向于使用最少的 JavaScript
• 基本的滚动显现效果已足够

在以下情况下使用 GSAP ScrollTrigger：

• 复杂的动画序列
• 精确同步滚动的动画
• 需要编排时间线
• 需要高级缓动／物理效果

资源

官方文档

• AOS：https://michalsnik.github.io/aos/
• GitHub：https://github.com/michalsnik/aos

关键脚本

• scripts/aos_generator.py - 生成 AOS HTML 样板代码
• scripts/config_builder.py - 构建 AOS 配置

参考资料

• references/aos_api.md - 完整的 AOS API 参考
• references/animation_catalog.md - 所有内置动画及演示
• references/integration_patterns.md - 框架集成指南

入门资源

• assets/starter_aos/ - 完整的 AOS 入门模板
• assets/examples/ - 可用于生产环境的模式

相关技能

• gsap-scrolltrigger：用于复杂的滚动驱动动画
• motion-framer：用于带物理效果的 React 专属动画
• locomotive-scroll：用于带视差效果的平滑滚动
• animated-component-libraries：用于预构建的动画 React 组件