argon-theme/.kiro/specs/pjax-lazyload-optimization/tasks.md

# 实施计划：PJAX 和 LazyLoad 优化

## 概述

本实施计划将 Argon 主题的 PJAX 和 LazyLoad 功能优化分解为离散的编码步骤。每个任务都基于设计文档，并引用具体的需求。

**实施策略：**
- 渐进式重构：优先修复关键问题，避免大规模重写
- 向后兼容：保持现有 API 和配置不变
- 测试驱动：每个功能模块都有对应的测试任务

## 任务

- [x] 1. 创建资源清理模块
  - 将 `pjax:beforeReplace` 中的清理逻辑封装到独立函数
  - 创建 `cleanupPjaxResources()` 函数
  - 包含 LazyLoad Observer、Zoomify、Tippy 的清理逻辑
  - 添加错误处理和日志记录
  - _需求：2.3, 6.1-6.5, 7.1-7.5_

- [ ]* 1.1 为资源清理模块编写单元测试
  - 测试 LazyLoad Observer 清理
  - 测试 Zoomify 实例清理
  - 测试 Tippy 实例清理
  - 测试错误处理逻辑
  - _需求：2.3, 6.1-6.5, 7.1-7.5_

- [x] 2. 优化 LazyLoad 初始化函数
  - [x] 2.1 添加 Observer 存在性检查
    - 在 `lazyloadInit()` 开头检查 `lazyloadObserver` 是否已存在
    - 如果存在，先调用 `disconnect()` 再创建新实例
    - _需求：2.1, 2.2_
  
  - [x] 2.2 创建优化的图片加载函数
    - 创建 `loadImageOptimized()` 函数
    - 使用 `requestAnimationFrame` 替代 `setTimeout`
    - 实现 fadeIn 和 slideDown 效果
    - _需求：3.1, 3.2, 3.3_
  
  - [x] 2.3 创建加载效果应用函数
    - 创建 `applyLoadEffectOptimized()` 函数
    - 使用双重 `requestAnimationFrame` 确保渲染同步
    - 正确设置 CSS transition 和 transform 属性
    - _需求：3.1, 3.2, 3.3_
  
  - [x] 2.4 实现滚动监听降级方案
    - 创建 `lazyloadFallback()` 函数
    - 使用节流函数优化性能
    - 绑定 scroll 和 resize 事件监听器
    - _需求：2.4_
  
  - [x] 2.5 优化图片状态清理
    - 使用正则表达式移除所有 `lazyload-style-*` 类名
    - 确保 `data-src` 属性被移除
    - _需求：3.5_

- [ ]* 2.6 为 LazyLoad 模块编写属性测试
  - **属性 2: LazyLoad Observer 清理完整性**
  - **验证：需求 2.1, 2.2**
  
- [ ]* 2.7 为图片加载效果编写属性测试
  - **属性 5: 图片加载效果使用 requestAnimationFrame**
  - **属性 6: 图片加载效果 CSS 属性正确性**
  - **验证：需求 3.1, 3.2, 3.3**

- [ ]* 2.8 为图片加载失败处理编写属性测试
  - **属性 7: 图片加载失败处理**
  - **属性 8: LazyLoad 类名清理**
  - **验证：需求 3.4, 3.5, 10.4**

- [x] 3. 优化 PJAX 事件处理器
  - [x] 3.1 重构 `pjax:beforeReplace` 事件处理器
    - 调用 `cleanupPjaxResources()` 函数
    - 保留 UI 状态更新逻辑
    - 保留滚动位置处理逻辑
    - _需求：2.3, 6.1-6.5, 7.1-7.5_
  
  - [x] 3.2 重构 `pjax:complete` 事件处理器
    - 移除重复的初始化调用
    - 保持单次调用 `waterflowInit()`、`lazyloadInit()`、`zoomifyInit()`
    - 添加错误处理包裹所有初始化函数
    - _需求：1.1, 1.2, 1.3_
  
  - [x] 3.3 重构 `pjax:end` 事件处理器
    - 移除 `setTimeout` 中的重复初始化调用
    - 只保留 `resetMobileCatalog()` 和 `resetGT4Captcha()` 调用
    - _需求：1.1, 1.2, 1.3, 8.1, 8.2_

- [ ]* 3.4 为 PJAX 事件处理编写属性测试
  - **属性 1: PJAX 初始化函数单次调用**
  - **属性 3: PJAX beforeReplace 资源清理**
  - **验证：需求 1.1-1.3, 2.3, 6.1-6.5, 7.1-7.5**

- [x] 4. 创建 GT4 验证码重置函数
  - 将 `pjax:end` 中的 GT4 重置逻辑封装到 `resetGT4Captcha()` 函数
  - 重置状态变量（`geetestVerified`、`geetestAutoSubmitting`）
  - 清空隐藏字段
  - 清空容器 DOM
  - 调用初始化函数
  - 添加错误处理
  - _需求：4.1, 4.2, 4.3, 4.4, 4.5_

- [ ]* 4.1 为 GT4 验证码重置编写属性测试
  - **属性 9: GT4 验证码状态重置完整性**
  - **属性 10: GT4 验证码初始化错误处理**
  - **验证：需求 4.1-4.5**

- [x] 5. 优化滚动位置管理
  - [x] 5.1 验证 `pjax:click` 事件中的滚动位置设置逻辑
    - 确认分页链接的滚动位置计算正确
    - 确认 Banner 封面模式的条件判断正确
    - _需求：5.1, 5.2, 5.5_
  
  - [x] 5.2 验证 `pjax:complete` 事件中的滚动位置恢复逻辑
    - 确认 `pjaxScrollTop > 0` 时恢复滚动位置
    - 确认恢复后 `pjaxScrollTop` 被重置为 0
    - _需求：5.3, 5.4_

- [ ]* 5.3 为滚动位置管理编写属性测试
  - **属性 11: 滚动位置恢复正确性**
  - **属性 12: 分页链接滚动位置计算**
  - **验证：需求 5.2-5.5**

- [x] 6. 检查点 - 确保所有测试通过
  - 运行所有单元测试
  - 运行所有属性测试
  - 检查代码覆盖率（目标：≥ 80%）
  - 如有问题，询问用户

- [x] 7. 添加降级方案和兼容性检查
  - [x] 7.1 为 IntersectionObserver 添加特性检测
    - 确认 `'IntersectionObserver' in window` 检查存在
    - 确认降级方案被正确调用
    - _需求：2.4_
  
  - [x] 7.2 为第三方库添加存在性检查
    - 检查 `typeof tippy !== 'undefined'`
    - 检查 `typeof MathJax !== 'undefined'`
    - 检查 `typeof renderMathInElement !== 'undefined'`
    - _需求：4.5_

- [ ]* 7.3 为降级方案编写属性测试
  - **属性 4: IntersectionObserver 降级方案**
  - **验证：需求 2.4**

- [x] 8. 代码审查和优化
  - [x] 8.1 检查所有错误处理
    - 确保所有 try-catch 块都有适当的日志记录
    - 确保错误不会阻塞其他功能
    - _需求：4.5_
  
  - [x] 8.2 检查代码风格
    - 使用 Tab 缩进
    - 使用单引号
    - 使用严格相等 `===`
    - 添加 JSDoc 注释
  
  - [x] 8.3 优化性能
    - 检查是否有不必要的 DOM 查询
    - 检查是否有重复的计算
    - 使用 `{passive: true}` 优化滚动事件监听器

- [ ] 9. 集成测试
  - [ ] 9.1 测试完整的 PJAX 页面切换流程
    - 测试单次切换
    - 测试多次连续切换
    - 测试快速点击多个链接
  
  - [ ] 9.2 测试 LazyLoad 在 PJAX 后的工作状态
    - 测试图片懒加载
    - 测试加载效果
    - 测试降级方案
  
  - [ ] 9.3 测试资源清理
    - 测试内存使用情况
    - 测试事件监听器数量
    - 测试 DOM 元素清理

- [ ] 10. 最终检查点 - 确保所有测试通过
  - 运行所有单元测试
  - 运行所有属性测试
  - 运行所有集成测试
  - 检查代码覆盖率
  - 如有问题，询问用户

- [x] 11. 文档更新
  - 更新代码注释
  - 添加 JSDoc 文档
  - 更新 CHANGELOG（如果存在）
  - 记录优化前后的性能对比

## 注意事项

- 任务标记 `*` 的为可选测试任务，可以跳过以加快 MVP 开发
- 每个任务都引用了具体的需求编号，便于追溯
- 检查点任务确保增量验证
- 属性测试标注了对应的设计属性编号
- 所有修改都在 `argontheme.js` 文件中进行
- 保持向后兼容，不修改全局变量名和配置选项