scroll-reveal-libraries

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scroll Reveal Libraries

滚动显示动画库

Overview

概述

This skill covers AOS (Animate On Scroll), a lightweight CSS-driven library for scroll-triggered animations. AOS excels at simple fade, slide, and zoom effects activated when elements enter the viewport.

Key Features:

Minimal Setup: Single JavaScript file + CSS
Data Attribute API: Configure animations in HTML
Performance: CSS-driven, GPU-accelerated animations
50+ Built-in Animations: Fades, slides, zooms, flips
Framework Agnostic: Works with vanilla JS, React, Vue, etc.

When to Use:

Marketing/landing pages with simple scroll effects
Content-heavy sites (blogs, documentation)
Quick prototypes requiring scroll animations
Projects where GSAP/Framer Motion complexity isn't needed

When NOT to Use:

Complex animation timelines or orchestration → Use GSAP ScrollTrigger
Physics-based animations → Use React Spring or Framer Motion
Precise scroll-synced animations → Use GSAP ScrollTrigger
Heavy interactive animations → Use Framer Motion

本技能介绍AOS（Animate On Scroll），这是一个轻量级的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

Core Concepts

核心概念

Installation

安装

CDN (Quickest):

html

<head>
  <link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
</head>
<body>
  <!-- Content with data-aos attributes -->

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

NPM/Yarn (Recommended):

bash

npm install aos@next

CDN（最快方式）:

html

<head>
  <link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
</head>
<body>
  <!-- 带有data-aos属性的内容 -->

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

NPM/Yarn（推荐）:

bash

npm install aos@next

or

或

yarn add aos@next


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

AOS.init();

yarn add aos@next


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

AOS.init();

Basic Usage

基础用法

Apply animations using the

data-aos

attribute:

html

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

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

<!-- Slide from right -->
<div data-aos="slide-left">Content</div>

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

通过

data-aos

属性应用动画:

html

<!-- 淡入 -->
<div data-aos="fade-in">内容</div>

<!-- 向上淡入 -->
<div data-aos="fade-up">内容</div>

<!-- 从右侧滑入 -->
<div data-aos="slide-left">内容</div>

<!-- 放大进入 -->
<div data-aos="zoom-in">内容</div>

Configuration Options

配置选项

Global Configuration:

javascript

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
});

Per-Element Overrides:

html

<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>

全局配置:

javascript

AOS.init({
  // 动画设置
  duration: 800,  // 动画时长（毫秒）: 0-3000
  delay: 0,       // 动画延迟（毫秒）: 0-3000
  offset: 120,    // 触发点偏移量（像素）
  easing: 'ease', // 缓动函数
  once: false,    // 是否仅动画一次（true）或每次滚动都触发（false）
  mirror: false,  // 滚动超过元素时是否反向动画

  // 触发位置
  anchorPlacement: 'top-bottom', // 触发动画的元素位置

  // 性能
  disable: false,                // 在手机/平板上禁用
  startEvent: 'DOMContentLoaded', // 初始化事件
  debounceDelay: 50,             // 窗口大小调整防抖延迟
  throttleDelay: 99              // 滚动事件节流延迟
});

元素级覆盖配置:

html

<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"
>
  自定义配置元素
</div>

Common Patterns

常见模式

1. Landing Page Hero Section

1. 着陆页 hero 区域

html

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

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

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

html

<section class="hero">
  <!-- 分阶段显示的标题文字 -->
  <h1
    data-aos="fade-down"
    data-aos-duration="800"
  >
    欢迎来到未来
  </h1>

  <!-- 延迟显示的副标题 -->
  <p
    data-aos="fade-up"
    data-aos-delay="200"
    data-aos-duration="600"
  >
    将你的想法变为现实
  </p>

  <!-- CTA按钮 -->
  <button
    data-aos="zoom-in"
    data-aos-delay="400"
    data-aos-duration="500"
  >
    立即开始
  </button>
</section>

2. Feature Cards Grid

2. 功能卡片网格

html

<div class="features-grid">
  <!-- Stagger cards with increasing delays -->
  <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>

html

<div class="features-grid">
  <!-- 递增延迟显示的卡片 -->
  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    <h3>功能1</h3>
    <p>描述...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="100"
  >
    <h3>功能2</h3>
    <p>描述...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    <h3>功能3</h3>
    <p>描述...</p>
  </div>
</div>

3. Alternating Content Sections

3. 交替内容区块

html

<!-- Content from left -->
<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>

<!-- Content from right -->
<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>

html

<!-- 内容从左侧滑入 -->
<div class="section">
  <div
    class="content"
    data-aos="slide-right"
    data-aos-duration="800"
  >
    <h2>区块标题</h2>
    <p>内容从左侧滑入...</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>区块标题</h2>
    <p>内容从右侧滑入...</p>
  </div>
</div>

4. Scroll-Triggered Testimonials

4. 滚动触发的客户评价

html

<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>

html

<div class="testimonials">
  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
  >
    <blockquote>"产品太棒了！"</blockquote>
    <cite>- 约翰·多伊</cite>
  </div>

  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
    data-aos-delay="100"
  >
    <blockquote>"超出预期"</blockquote>
    <cite>- 简·史密斯</cite>
  </div>
</div>

5. Custom Anchor Triggers

5. 自定义锚点触发

Trigger animations based on a different element's scroll position:

html

<!-- Fixed sidebar animates based on main content scroll -->
<div class="main-content">
  <div id="trigger-point" data-aos-id="sidebar-trigger">
    <!-- Content -->
  </div>
</div>

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

基于其他元素的滚动位置触发动画:

html

<!-- 固定侧边栏根据主内容滚动触发动画 -->
<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"
>
  侧边栏内容
</aside>

6. Sequential Animation Chain

6. 顺序动画链

html

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

  <!-- Step 2: Description -->
  <p
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    Follow these simple steps
  </p>

  <!-- Step 3-5: Process cards -->
  <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>

html

<div class="animation-sequence">
  <!-- 步骤1：标题 -->
  <h2
    data-aos="fade-down"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    我们的流程
  </h2>

  <!-- 步骤2：描述 -->
  <p
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    遵循以下简单步骤
  </p>

  <!-- 步骤3-5：流程卡片 -->
  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="400"
  >
    步骤1
  </div>

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

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

7. Image Gallery with Zoom Effects

7. 带缩放效果的图片画廊

html

<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>

html

<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>

Integration Patterns

框架集成模式

React Integration

React集成

Basic Setup:

jsx

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>
  );
}

Refreshing on Route Changes:

jsx

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>;
}

Dynamic Content Updates:

jsx

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>
  );
}

Component Wrapper Pattern:

jsx

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>

基础配置:

jsx

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">欢迎</h1>
      <p data-aos="fade-up">这里是内容</p>
    </div>
  );
}

路由切换时刷新:

jsx

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

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

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

  // 路由切换时刷新AOS
  useEffect(() => {
    AOS.refresh();
  }, [location]);

  return <Routes>{/* 路由 */}</Routes>;
}

动态内容更新:

jsx

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: '新项目' }]);

    // 刷新AOS以检测新元素
    setTimeout(() => AOS.refresh(), 50);
  };

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

组件包装器模式:

jsx

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>
  );
}

// 使用方式
<AnimatedSection animation="slide-right" delay={200}>
  <h2>动画内容</h2>
</AnimatedSection>

Vue.js Integration

Vue.js集成

vue

<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>

vue

<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() {
    // 组件更新时刷新
    this.$nextTick(() => {
      AOS.refresh();
    });
  },
  data() {
    return {
      items: [/*...*/]
    };
  }
};
</script>

Next.js Integration

Next.js集成

jsx

// 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;

jsx

// 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>
  );
}

jsx

// 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;

jsx

// pages/index.js
export default function Home() {
  return (
    <main>
      <h1 data-aos="fade-down">Next.js + AOS</h1>
      <p data-aos="fade-up">服务端渲染内容带动画</p>
    </main>
  );
}

Performance Optimization

性能优化

1. Disable on Mobile Devices

1. 在移动设备上禁用

javascript

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

javascript

AOS.init({
  disable: 'mobile', // 在移动设备上禁用
  // 或使用自定义逻辑函数
  disable: function() {
    return window.innerWidth < 768;
  }
});

2. Use Once for Better Performance

2. 启用单次动画提升性能

javascript

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

javascript

AOS.init({
  once: true, // 仅动画一次（提升性能）
  mirror: false // 不反向动画
});

3. Optimize Throttle and Debounce

3. 优化节流与防抖

javascript

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

javascript

AOS.init({
  throttleDelay: 99,  // 滚动事件节流延迟（默认值）
  debounceDelay: 50   // 窗口大小调整防抖延迟（默认值）
});

4. Disable Mutation Observer for Static Content

4. 静态内容禁用Mutation Observer

javascript

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

javascript

AOS.init({
  disableMutationObserver: true // 纯静态内容时禁用
});

5. Reduce Animation Complexity

5. 降低动画复杂度

html

<!-- Simpler animations perform better -->
<div data-aos="fade-in">Simple fade</div>

<!-- Complex animations may cause jank -->
<div data-aos="flip-left">Complex flip</div>

html

<!-- 简单动画性能更好 -->
<div data-aos="fade-in">简单淡入</div>

<!-- 复杂动画可能导致卡顿 -->
<div data-aos="flip-left">复杂翻转</div>

6. Use RequestIdleCallback for Initialization

6. 使用RequestIdleCallback初始化

javascript

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

javascript

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

Common Pitfalls

常见陷阱

1. Forgetting to Refresh After DOM Changes

1. DOM变更后忘记刷新

Problem: New elements don't animate after being added dynamically.

Solution: Call

AOS.refresh()

AOS.refreshHard()

javascript

// 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

问题：动态添加的新元素无法触发动画。

解决：调用

AOS.refresh()

或

AOS.refreshHard()

javascript

// 向DOM添加元素后
const newElement = document.createElement('div');
newElement.setAttribute('data-aos', 'fade-in');
container.appendChild(newElement);

// 刷新AOS
AOS.refresh(); // 重新计算位置
// 或
AOS.refreshHard(); // 完全重新初始化

2. Animations Not Working in React

2. React中动画不工作

Problem: AOS doesn't detect elements on first render or route changes.

Solution: Initialize in

useEffect

and refresh on route/content changes:

jsx

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

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

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

解决：在

useEffect

中初始化，并在路由/内容变更时刷新:

jsx

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

useEffect(() => {
  AOS.refresh(); // 路由切换时刷新
}, [location.pathname]);

3. Scroll Performance Issues

3. 滚动性能问题

Problem: Page scrolling feels janky with many animated elements.

Solution: Reduce animated elements and use

once: true

javascript

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

问题：页面滚动时带有大量动画元素，感觉卡顿。

解决：减少动画元素数量并启用

once: true

javascript

AOS.init({
  once: true, // 仅动画一次
  disable: window.innerWidth < 768 // 移动设备禁用
});

4. CSS Conflicts

4. CSS冲突

Problem: Custom CSS interferes with AOS animations.

Solution: Use more specific selectors and avoid

!important

css

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

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

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

解决：使用更具体的选择器，避免使用

!important

css

/* 错误：与AOS冲突 */
div {
  opacity: 1 !important;
}

/* 正确：具体选择器 */
.my-content > div {
  /* 样式 */
}

5. Anchor Placement Confusion

5. 锚点位置混淆

Problem: Animations trigger at unexpected scroll positions.

Solution: Understand anchor placement options:

javascript

// 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"

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

解决：理解锚点位置选项:

javascript

// 元素顶部触及视口底部时触发
data-aos-anchor-placement="top-bottom"

// 元素中心触及视口中心时触发
data-aos-anchor-placement="center-center"

// 元素底部触及视口顶部时触发
data-aos-anchor-placement="bottom-top"

6. Duration/Delay Limits

6. 时长/延迟限制

Problem: Values above 3000ms don't work.

Solution: Add custom CSS for extended durations:

css

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

html

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

问题：超过3000ms的值不生效。

解决：添加自定义CSS支持更长时长:

css

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

html

<div data-aos="fade-in" data-aos-duration="4000">
  长时长动画
</div>

Built-in Animations

内置动画

Fade Animations

淡入动画

```
fade-in
```
- Simple fade in
```
fade-up
```
- Fade in from bottom
```
fade-down
```
- Fade in from top
```
fade-left
```
- Fade in from right
```
fade-right
```
- Fade in from left
```
fade-up-right
```
- Diagonal fade
```
fade-up-left
```
- Diagonal fade
```
fade-down-right
```
- Diagonal fade
```
fade-down-left
```
- Diagonal fade

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

Slide Animations

滑动动画

```
slide-up
```
- Slide from bottom
```
slide-down
```
- Slide from top
```
slide-left
```
- Slide from right
```
slide-right
```
- Slide from left

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

Zoom Animations

缩放动画

```
zoom-in
```
- Zoom in
```
zoom-in-up
```
- Zoom in from bottom
```
zoom-in-down
```
- Zoom in from top
```
zoom-in-left
```
- Zoom in from right
```
zoom-in-right
```
- Zoom in from left
```
zoom-out
```
- Zoom out
```
zoom-out-up
```
- Zoom out to top
```
zoom-out-down
```
- Zoom out to bottom
```
zoom-out-left
```
- Zoom out to left
```
zoom-out-right
```
- Zoom out to 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 Animations

翻转动画

```
flip-up
```
- Flip from bottom
```
flip-down
```
- Flip from top
```
flip-left
```
- Flip from right
```
flip-right
```
- Flip from left

```
flip-up
```
- 从底部翻转
```
flip-down
```
- 从顶部翻转
```
flip-left
```
- 从右侧翻转
```
flip-right
```
- 从左侧翻转

Custom Animations

自定义动画

Create custom animations with CSS:

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);
  }
}

html

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

使用CSS创建自定义动画:

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);
  }
}

html

<div data-aos="custom-slide-bounce">
  自定义动画
</div>

Comparison with Alternatives

与替代方案对比

AOS vs GSAP ScrollTrigger

Feature	AOS	GSAP ScrollTrigger
Complexity	Simple, data-attribute based	Advanced, JavaScript API
Use Case	Simple reveals	Complex timelines
File Size	~13KB	~27KB (GSAP) + ScrollTrigger
Performance	CSS-driven	JavaScript-driven
Learning Curve	Minutes	Hours
Customization	Limited	Extensive
Best For	Marketing pages	Interactive experiences

Use AOS when:

Simple fade/slide/zoom effects
Quick implementation needed
Minimal JavaScript preferred
Basic scroll reveals sufficient

Use GSAP ScrollTrigger when:

Complex animation sequences
Precise scroll-synced animations
Timeline orchestration needed
Advanced easing/physics required

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

选择AOS的场景:

简单淡入/滑动/缩放效果
需要快速实现
偏好最少JavaScript
基础滚动显示足够满足需求

选择GSAP ScrollTrigger的场景:

复杂动画序列
精确滚动同步动画
需要时间线编排
高级缓动/物理特性需求

Resources

资源

Official Documentation

官方文档

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

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

Key Scripts

关键脚本

```
scripts/aos_generator.py
```
- Generate AOS HTML boilerplate
```
scripts/config_builder.py
```
- Build AOS configuration

```
scripts/aos_generator.py
```
- 生成AOS HTML模板
```
scripts/config_builder.py
```
- 构建AOS配置

References

参考资料

```
references/aos_api.md
```
- Complete AOS API reference
```
references/animation_catalog.md
```
- All built-in animations with demos
```
references/integration_patterns.md
```
- Framework integration guides

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

Starter Assets

入门资源

```
assets/starter_aos/
```
- Complete AOS starter template
```
assets/examples/
```
- Production-ready patterns

```
assets/starter_aos/
```
- 完整AOS入门模板
```
assets/examples/
```
- 生产可用的示例模式