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

实施计划：PJAX 和 LazyLoad 优化

概述

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

实施策略：

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

任务

• 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

• 2. 优化 LazyLoad 初始化函数

  • 2.1 添加 Observer 存在性检查

    • 在 lazyloadInit() 开头检查 lazyloadObserver 是否已存在
    • 如果存在，先调用 disconnect() 再创建新实例
    • 需求：2.1, 2.2

  • 2.2 创建优化的图片加载函数

    • 创建 loadImageOptimized() 函数
    • 使用 requestAnimationFrame 替代 setTimeout
    • 实现 fadeIn 和 slideDown 效果
    • 需求：3.1, 3.2, 3.3

  • 2.3 创建加载效果应用函数

    • 创建 applyLoadEffectOptimized() 函数
    • 使用双重 requestAnimationFrame 确保渲染同步
    • 正确设置 CSS transition 和 transform 属性
    • 需求：3.1, 3.2, 3.3

  • 2.4 实现滚动监听降级方案

    • 创建 lazyloadFallback() 函数
    • 使用节流函数优化性能
    • 绑定 scroll 和 resize 事件监听器
    • 需求：2.4

  • 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

• 3. 优化 PJAX 事件处理器

  • 3.1 重构 pjax:beforeReplace 事件处理器

    • 调用 cleanupPjaxResources() 函数
    • 保留 UI 状态更新逻辑
    • 保留滚动位置处理逻辑
    • 需求：2.3, 6.1-6.5, 7.1-7.5

  • 3.2 重构 pjax:complete 事件处理器

    • 移除重复的初始化调用
    • 保持单次调用 waterflowInit()、lazyloadInit()、zoomifyInit()
    • 添加错误处理包裹所有初始化函数
    • 需求：1.1, 1.2, 1.3

  • 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

• 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

• 5. 优化滚动位置管理

  • 5.1 验证 pjax:click 事件中的滚动位置设置逻辑

    • 确认分页链接的滚动位置计算正确
    • 确认 Banner 封面模式的条件判断正确
    • 需求：5.1, 5.2, 5.5

  • 5.2 验证 pjax:complete 事件中的滚动位置恢复逻辑

    • 确认 pjaxScrollTop > 0 时恢复滚动位置
    • 确认恢复后 pjaxScrollTop 被重置为 0
    • 需求：5.3, 5.4

• * 5.3 为滚动位置管理编写属性测试

  • 属性 11: 滚动位置恢复正确性
  • 属性 12: 分页链接滚动位置计算
  • 验证：需求 5.2-5.5

• 6. 检查点 - 确保所有测试通过

  • 运行所有单元测试
  • 运行所有属性测试
  • 检查代码覆盖率（目标：≥ 80%）
  • 如有问题，询问用户

• 7. 添加降级方案和兼容性检查

  • 7.1 为 IntersectionObserver 添加特性检测

    • 确认 'IntersectionObserver' in window 检查存在
    • 确认降级方案被正确调用
    • 需求：2.4

  • 7.2 为第三方库添加存在性检查

    • 检查 typeof tippy !== 'undefined'
    • 检查 typeof MathJax !== 'undefined'
    • 检查 typeof renderMathInElement !== 'undefined'
    • 需求：4.5

• * 7.3 为降级方案编写属性测试

  • 属性 4: IntersectionObserver 降级方案
  • 验证：需求 2.4

• 8. 代码审查和优化

  • 8.1 检查所有错误处理

    • 确保所有 try-catch 块都有适当的日志记录
    • 确保错误不会阻塞其他功能
    • 需求：4.5

  • 8.2 检查代码风格

    • 使用 Tab 缩进
    • 使用单引号
    • 使用严格相等 ===
    • 添加 JSDoc 注释

  • 8.3 优化性能

    • 检查是否有不必要的 DOM 查询
    • 检查是否有重复的计算
    • 使用 {passive: true} 优化滚动事件监听器

• 9. 集成测试

  • 9.1 测试完整的 PJAX 页面切换流程

    • 测试单次切换
    • 测试多次连续切换
    • 测试快速点击多个链接

  • 9.2 测试 LazyLoad 在 PJAX 后的工作状态

    • 测试图片懒加载
    • 测试加载效果
    • 测试降级方案

  • 9.3 测试资源清理

    • 测试内存使用情况
    • 测试事件监听器数量
    • 测试 DOM 元素清理

• 10. 最终检查点 - 确保所有测试通过

  • 运行所有单元测试
  • 运行所有属性测试
  • 运行所有集成测试
  • 检查代码覆盖率
  • 如有问题，询问用户

• 11. 文档更新

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

注意事项

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