astro-jiao77.cn/docs/ANIMATION_DELAY_SYSTEM.md

动画延迟系统：从固定值到动态变量的升级

系统概述

已成功将报告页面的动画延迟系统从固定值改进为基于变量的动态计算系统，提供更好的协调性和可维护性。

核心改进

1. 动态时序计算模块

• 文件: /src/scripts/animation-timing.ts
• 功能: 提供统一的动画时序计算工具
• 优势: 数学关系清晰，易于维护和调整

2. 基础延迟配置

const BASE_DELAYS = {
  HERO: 160,             // 首屏动画延迟
  FIRST_SECTION: 280,    // 第一章节基础延迟
  SECTION_INCREMENT: 160,// 后续章节递增
  SUB_ELEMENT_BASE: 50,
  SUB_ELEMENT_INCREMENT: 50,
  NESTED_ELEMENT_BASE: 100,
  IMAGE_BASE: 50,
};

3. 核心计算函数

章节基础延迟

getSectionBaseDelay(index: number): number
// 计算公式: 280 + index * 160

子元素延迟

getChildDelay(parentDelay: number, childIndex: number): number
// 计算公式: parentDelay + BASE_DELAYS.CHILD + (childIndex * BASE_DELAYS.CHILD)

嵌套元素延迟

getNestedDelay(parentDelay: number, nestedIndex: number): number
// 计算公式: parentDelay + BASE_DELAYS.NESTED + (nestedIndex * BASE_DELAYS.NESTED)

图片元素延迟

getImageDelay(baseDelay: number, imageIndex: number): number
// 计算公式: baseDelay + BASE_DELAYS.IMAGE + (imageIndex * BASE_DELAYS.IMAGE)

应用实例

1. 20250609 报告 (完全迁移)

• 章节延迟: 使用 SECTION_DELAYS 常量配置
• 子元素: 技术挑战卡片、深度分析卡片等使用 getChildDelay()
• 嵌套元素: 卡片内的细节使用 getNestedDelay()
• 图片序列: 使用 getImageDelay() 处理多图展示

2. 模板系统 (完全迁移)

• 配置: TEMPLATE_SECTION_DELAYS 常量定义各章节基础延迟
• 标准化: 所有模板组件采用统一的动态计算方式
• 灵活性: 便于快速调整整体动画节奏

动画时序层级关系

章节延迟 (Section)
├── 子元素延迟 (Child) = 父级 + 基础增量 + 索引增量
│   └── 嵌套元素延迟 (Nested) = 父级 + 嵌套增量 + 索引增量
└── 图片延迟 (Image) = 基础 + 图片增量 + 索引增量

延迟时间示例

典型章节时序：

• 概述章节: 280ms (基础)
• 分析章节: 440ms (基础 + 160ms)
• 解决方案: 600ms (基础 + 320ms)
• 对比分析: 760ms (基础 + 480ms)
• 实验结果: 920ms (基础 + 640ms)
• 总结展望: 1080ms (基础 + 800ms)

子元素时序（以分析章节为例）：

• 技术挑战1: 490ms (440ms + 50ms)
• 技术挑战2: 540ms (440ms + 50ms + 50ms)
• 技术挑战3: 590ms (440ms + 50ms + 100ms)

技术优势

1. 可维护性

• 统一的计算逻辑，避免魔数
• 便于全局调整动画节奏
• 清晰的层级关系

2. 一致性

• 数学关系确保视觉协调
• 标准化的动画模式
• 可预测的用户体验

3. 扩展性

• 易于添加新的延迟类型
• 支持复杂的嵌套结构
• 灵活的配置选项

4. 开发效率

• 无需手动计算延迟值
• 自动处理父子关系
• 减少动画冲突

构建验证

✅ 所有页面构建成功
✅ TypeScript 类型检查通过
✅ 无运行时错误
✅ 动画时序正常工作

未来扩展

1. 批量延迟: 使用 getBatchDelays() 处理大量元素
2. 自定义配置: 支持页面级别的延迟配置覆盖
3. 响应式延迟: 根据屏幕尺寸调整动画时序
4. 性能优化: 考虑减少长延迟对用户体验的影响

使用指南

导入工具函数：

import { 
  getSectionBaseDelay, 
  getChildDelay, 
  getNestedDelay, 
  getImageDelay 
} from '../scripts/animation-timing';

定义章节延迟：

const SECTION_DELAYS = {
  OVERVIEW: getSectionBaseDelay(0),    // 280ms
  ANALYSIS: getSectionBaseDelay(1),    // 440ms
  SOLUTION: getSectionBaseDelay(2),    // 600ms
};

应用到组件：

<AnimatedElement animation="fadeInUp" delay={SECTION_DELAYS.ANALYSIS} trigger="scroll">
  <div class="section-content">
    <AnimatedElement animation="fadeInUp" delay={getChildDelay(SECTION_DELAYS.ANALYSIS, 0)} trigger="scroll">
      <div class="child-element">子元素内容</div>
    </AnimatedElement>
  </div>
</AnimatedElement>

这个动态延迟系统现在为整个项目提供了一致、可维护和协调的动画体验！