nanhaoluo/argon-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 完成 PJAX 和 Lazyload 代码审查和文档

Browse Source 
- 创建代码审查总结文档（code-review-summary.md）
  - 评估代码质量，列出优点和需要改进的地方
  - 为所有关键函数提供 JSDoc 文档说明
  - 包含性能优化、安全性和兼容性检查
  - 提供测试建议和改进建议

- 创建 JSDoc 注释模板（jsdoc-templates.md）
  - 为 80+ 个关键函数提供完整的 JSDoc 模板
  - 包含参数类型、返回值和使用示例
  - 涵盖 Cookie、搜索、懒加载、PJAX、评论等所有模块
  - 可直接复制使用，提高开发效率

- 创建代码风格检查清单（code-style-checklist.md）
  - 14 项代码风格检查，总体评分 8.2/10
  - 详细的改进建议和优先级划分
  - 提供 ESLint 和 Prettier 配置建议
  - 包含代码提交前和审查时的检查清单

- 更新任务状态
  - 标记任务 18（文档和代码审查）为已完成

总体评价：
- 代码质量良好，功能完善，性能优化到位
- 主要优点：模块化清晰、错误处理完善、性能优化充分
- 需要改进：JSDoc 注释不完整、代码风格不统一、全局变量较多
This commit is contained in:
nanhaoluo
2026-01-25 09:47:13 +08:00
parent 9f31bbe372
commit bfaeaa2ca2
6 changed files with 3110 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
.kiro/specs/pjax-lazyload-fix/requirements.md Normal file
View File

@@ -0,0 +1,280 @@
# Requirements Document
## Introduction
本规范旨在全面优化 Argon WordPress 主题中 PJAX 页面无刷新跳转、Lazyload 图片懒加载和 Mermaid 图表渲染功能。当前实现存在以下问题：
**核心问题：**
- 资源泄漏：Observer 和第三方库实例未正确清理
- 脚本执行失败：新页面的内联脚本未执行
- 样式错误：动态样式未清理导致样式冲突
- Mermaid 初始化时序问题：清除缓存后首次加载报语法错误
- Mermaid 交互体验差：操作框遮挡内容、缩放不流畅、拖拽不灵敏
**优化目标：**
1. 完善 PJAX 生命周期管理，消除资源泄漏
2. 优化 Lazyload 性能，提升图片加载体验
3. 增强 Mermaid 显示效果和交互功能
4. 提升整体稳定性和用户体验
## Glossary
- **PJAX**: 使用 Ajax 和 pushState 实现的页面无刷新跳转技术
- **Lazyload**: 图片懒加载技术，延迟加载视口外的图片
- **Observer**: IntersectionObserver API，用于监听元素可见性
- **Mermaid**: 基于文本的图表生成库
- **Resource_Cleanup**: 资源清理，包括断开 Observer、销毁实例、移除事件监听器
- **Lifecycle**: 生命周期，指 PJAX 页面切换的各个阶段
- **DOM_Cache**: DOM 元素缓存，避免重复查询
- **Event_Delegation**: 事件委托，在父元素上监听子元素事件
- **Zoom_Controls**: 缩放控制，Mermaid 图表的放大缩小功能
- **Drag_Pan**: 拖拽平移，Mermaid 图表的拖拽移动功能
- **Toolbar**: 工具栏，Mermaid 图表的操作按钮组
- **Fullscreen**: 全屏模式，Mermaid 图表的全屏查看功能
## Requirements
### Requirement 1: PJAX 生命周期管理
**User Story:** 作为开发者，我希望 PJAX 页面切换时能正确管理资源生命周期，以避免内存泄漏和功能失效。
#### Acceptance Criteria
1. WHEN PJAX 触发页面切换 THEN THE System SHALL 在 pjax:beforeReplace 事件中清理所有旧页面资源
2. WHEN 清理资源时 THEN THE System SHALL 断开所有 IntersectionObserver 连接并置空引用
3. WHEN 清理资源时 THEN THE System SHALL 销毁所有第三方库实例（Zoomify、Tippy、Mermaid）
4. WHEN 清理资源时 THEN THE System SHALL 移除所有动态添加的 style 和 script 标签
5. WHEN 新页面加载完成 THEN THE System SHALL 在 pjax:complete 事件中重新初始化所有功能模块
6. WHEN 初始化功能模块时 THEN THE System SHALL 为每个模块添加错误处理，确保单个模块失败不影响其他模块
7. WHEN 页面切换完成 THEN THE System SHALL 在 pjax:end 事件中执行特定任务（GT4 验证码重置、移动端目录重置）
8. WHEN 新页面包含内联脚本 THEN THE System SHALL 执行这些脚本
### Requirement 2: Lazyload 资源管理
**User Story:** 作为开发者，我希望 Lazyload 功能能正确管理 Observer 资源，避免内存泄漏。
#### Acceptance Criteria
1. WHEN 初始化 Lazyload THEN THE System SHALL 检查并清理旧的 Observer 实例
2. WHEN 清理 Observer THEN THE System SHALL 调用 disconnect() 方法并将引用置为 null
3. WHEN 页面切换时 THEN THE System SHALL 在 cleanupPjaxResources 函数中清理 Lazyload Observer
4. WHEN 图片加载完成 THEN THE System SHALL 取消对该图片的监听
5. WHEN 图片加载失败 THEN THE System SHALL 使用降级方案并清理相关资源
6. WHEN 懒加载禁用时 THEN THE System SHALL 立即加载所有图片而不创建 Observer
### Requirement 3: Mermaid 初始化时序
**User Story:** 作为用户，我希望 Mermaid 图表能在清除缓存后正确渲染，不出现语法错误。
#### Acceptance Criteria
1. WHEN Mermaid 库加载时 THEN THE System SHALL 检查库是否完全加载后再初始化
2. WHEN 初始化 Mermaid THEN THE System SHALL 添加加载状态检查，确保 mermaid.render 方法存在
3. WHEN Mermaid 渲染失败 THEN THE System SHALL 提供降级方案（旧版 API、init 方法）
4. WHEN 清除缓存后首次加载 THEN THE System SHALL 等待 Mermaid 库完全加载后再渲染
5. WHEN Mermaid 渲染出错 THEN THE System SHALL 显示友好的错误提示并保留原始代码
6. WHEN 页面切换时 THEN THE System SHALL 清理旧的 Mermaid 实例并重新渲染
### Requirement 4: 内联脚本执行
**User Story:** 作为开发者，我希望 PJAX 页面切换后能执行新页面中的内联脚本。
#### Acceptance Criteria
1. WHEN PJAX 加载新页面 THEN THE System SHALL 提取新页面中的所有 script 标签
2. WHEN 提取脚本时 THEN THE System SHALL 区分内联脚本和外部脚本
3. WHEN 执行内联脚本 THEN THE System SHALL 按照脚本在 DOM 中的顺序执行
4. WHEN 脚本执行失败 THEN THE System SHALL 捕获错误并记录日志，不中断其他脚本执行
5. WHEN 脚本包含 async 或 defer 属性 THEN THE System SHALL 尊重这些属性的执行时机
### Requirement 5: CSS 样式管理
**User Story:** 作为用户，我希望页面切换后样式保持正确，不出现样式丢失或错乱。
#### Acceptance Criteria
1. WHEN 页面切换前 THEN THE System SHALL 清理所有动态添加的 style 标签
2. WHEN 清理样式时 THEN THE System SHALL 保留主题核心样式，只清理页面特定样式
3. WHEN 新页面加载 THEN THE System SHALL 提取并应用新页面的 style 标签
4. WHEN 样式冲突时 THEN THE System SHALL 使用新页面的样式覆盖旧样式
5. WHEN 页面包含 scoped 样式 THEN THE System SHALL 正确处理样式作用域
### Requirement 6: 事件监听器管理
**User Story:** 作为开发者，我希望页面切换时能正确管理事件监听器，避免重复绑定和内存泄漏。
#### Acceptance Criteria
1. WHEN 页面切换前 THEN THE System SHALL 移除所有非委托的事件监听器
2. WHEN 使用事件委托 THEN THE System SHALL 在 document 或 body 上绑定监听器
3. WHEN 新页面加载 THEN THE System SHALL 重新绑定必要的事件监听器
4. WHEN 监听器绑定失败 THEN THE System SHALL 记录错误并继续执行
5. WHEN 使用第三方库的事件 THEN THE System SHALL 在清理时调用库提供的销毁方法
### Requirement 7: 性能优化
**User Story:** 作为用户，我希望页面切换流畅，不出现卡顿和延迟。
#### Acceptance Criteria
1. WHEN 滚动页面时 THEN THE System SHALL 使用节流函数限制事件处理频率
2. WHEN 初始化多个功能模块 THEN THE System SHALL 使用 requestAnimationFrame 优化渲染
3. WHEN 清理资源时 THEN THE System SHALL 批量处理，避免多次 DOM 操作
4. WHEN 加载图片时 THEN THE System SHALL 使用 IntersectionObserver 替代滚动监听
5. WHEN 页面切换时 THEN THE System SHALL 显示加载进度条，提供视觉反馈
### Requirement 8: 错误处理和降级
**User Story:** 作为开发者，我希望系统能优雅地处理错误，提供降级方案。
#### Acceptance Criteria
1. WHEN 功能模块初始化失败 THEN THE System SHALL 捕获错误并记录日志
2. WHEN IntersectionObserver 不支持 THEN THE System SHALL 使用滚动监听降级方案
3. WHEN Mermaid 渲染失败 THEN THE System SHALL 显示错误提示并保留原始代码
4. WHEN PJAX 加载失败 THEN THE System SHALL 回退到传统页面跳转
5. WHEN 第三方库未加载 THEN THE System SHALL 提供空实现，避免脚本错误
### Requirement 9: 调试和监控
**User Story:** 作为开发者，我希望能方便地调试和监控 PJAX 和 Lazyload 的运行状态。
#### Acceptance Criteria
1. WHEN 启用调试模式 THEN THE System SHALL 在控制台输出详细的生命周期日志
2. WHEN 资源清理时 THEN THE System SHALL 记录清理的资源类型和数量
3. WHEN 功能模块初始化 THEN THE System SHALL 记录初始化状态和耗时
4. WHEN 发生错误时 THEN THE System SHALL 记录错误堆栈和上下文信息
5. WHEN 性能异常时 THEN THE System SHALL 记录性能指标（内存占用、渲染时间）
### Requirement 10: 兼容性保证
**User Story:** 作为用户，我希望功能在不同浏览器和设备上都能正常工作。
#### Acceptance Criteria
1. WHEN 浏览器不支持 IntersectionObserver THEN THE System SHALL 使用滚动监听降级方案
2. WHEN 浏览器不支持 Promise THEN THE System SHALL 使用回调函数实现异步逻辑
3. WHEN 浏览器不支持 requestAnimationFrame THEN THE System SHALL 使用 setTimeout 降级
4. WHEN 移动端浏览器 THEN THE System SHALL 优化触摸事件处理
5. WHEN 旧版浏览器 THEN THE System SHALL 提供 polyfill 或禁用高级功能
### Requirement 11: Mermaid 工具栏优化
**User Story:** 作为用户，我希望 Mermaid 图表的工具栏不会遮挡图表内容，且操作更加便捷。
#### Acceptance Criteria
1. WHEN 鼠标移出图表区域 THEN THE System SHALL 自动隐藏工具栏，避免遮挡内容
2. WHEN 鼠标移入图表区域 THEN THE System SHALL 显示工具栏，提供操作按钮
3. WHEN 工具栏显示时 THEN THE System SHALL 使用半透明背景，不完全遮挡图表
4. WHEN 工具栏位置固定在右上角 THEN THE System SHALL 确保不与图表关键内容重叠
5. WHEN 移动端设备 THEN THE System SHALL 调整工具栏大小和位置，适配小屏幕
### Requirement 12: Mermaid 缩放功能增强
**User Story:** 作为用户，我希望 Mermaid 图表的缩放功能更加流畅和精确。
#### Acceptance Criteria
1. WHEN 使用鼠标滚轮缩放 THEN THE System SHALL 以鼠标位置为中心进行缩放
2. WHEN 缩放时 THEN THE System SHALL 使用 CSS transform 实现硬件加速
3. WHEN 缩放级别改变 THEN THE System SHALL 平滑过渡，避免突兀跳动
4. WHEN 缩放到最小或最大级别 THEN THE System SHALL 禁用对应的缩放按钮
5. WHEN 双击图表 THEN THE System SHALL 智能缩放到合适大小（适配容器或重置）
### Requirement 13: Mermaid 拖拽功能优化
**User Story:** 作为用户，我希望拖拽 Mermaid 图表时响应灵敏，不会误触其他操作。
#### Acceptance Criteria
1. WHEN 拖拽图表时 THEN THE System SHALL 改变鼠标光标为抓手样式
2. WHEN 拖拽时 THEN THE System SHALL 禁用文本选择，避免误选
3. WHEN 拖拽时 THEN THE System SHALL 使用 requestAnimationFrame 优化性能
4. WHEN 拖拽结束 THEN THE System SHALL 恢复正常光标和文本选择
5. WHEN 图表未缩放且完全可见 THEN THE System SHALL 禁用拖拽功能
### Requirement 14: Mermaid 全屏模式
**User Story:** 作为用户，我希望能全屏查看复杂的 Mermaid 图表，获得更好的阅读体验。
#### Acceptance Criteria
1. WHEN 点击全屏按钮 THEN THE System SHALL 将图表全屏显示
2. WHEN 全屏模式下 THEN THE System SHALL 保持缩放和拖拽功能可用
3. WHEN 全屏模式下 THEN THE System SHALL 显示退出全屏按钮
4. WHEN 按 ESC 键 THEN THE System SHALL 退出全屏模式
5. WHEN 退出全屏 THEN THE System SHALL 恢复图表原始状态（缩放级别和位置）
### Requirement 15: Mermaid 导出功能
**User Story:** 作为用户，我希望能导出 Mermaid 图表为图片或 SVG 文件。
#### Acceptance Criteria
1. WHEN 点击导出按钮 THEN THE System SHALL 显示导出选项（PNG、SVG）
2. WHEN 选择 PNG 导出 THEN THE System SHALL 将图表转换为 PNG 图片并下载
3. WHEN 选择 SVG 导出 THEN THE System SHALL 将 SVG 代码保存为文件并下载
4. WHEN 导出时 THEN THE System SHALL 保持图表当前的缩放级别和样式
5. WHEN 导出失败 THEN THE System SHALL 显示友好的错误提示
### Requirement 16: Mermaid 响应式优化
**User Story:** 作为移动端用户，我希望 Mermaid 图表能自适应屏幕大小，操作便捷。
#### Acceptance Criteria
1. WHEN 屏幕宽度小于 768px THEN THE System SHALL 调整工具栏按钮大小
2. WHEN 移动端设备 THEN THE System SHALL 支持双指缩放手势
3. WHEN 移动端设备 THEN THE System SHALL 支持单指拖拽移动
4. WHEN 移动端设备 THEN THE System SHALL 优化触摸事件响应速度
5. WHEN 横屏模式 THEN THE System SHALL 自动调整图表布局
### Requirement 17: Mermaid 主题同步
**User Story:** 作为用户，我希望 Mermaid 图表主题能自动跟随网站主题切换。
#### Acceptance Criteria
1. WHEN 网站切换到夜间模式 THEN THE System SHALL 自动将 Mermaid 图表切换到 dark 主题
2. WHEN 网站切换到日间模式 THEN THE System SHALL 自动将 Mermaid 图表切换到 default 主题
3. WHEN 主题切换时 THEN THE System SHALL 保持图表的缩放级别和位置
4. WHEN 主题切换时 THEN THE System SHALL 使用淡入淡出过渡效果
5. WHEN 主题切换失败 THEN THE System SHALL 保留原主题，不影响图表显示
### Requirement 18: Mermaid 性能优化
**User Story:** 作为开发者，我希望 Mermaid 图表渲染性能优化，减少页面卡顿。
#### Acceptance Criteria
1. WHEN 页面包含多个图表 THEN THE System SHALL 使用批量渲染，避免阻塞主线程
2. WHEN 图表渲染时 THEN THE System SHALL 显示加载动画，提供视觉反馈
3. WHEN 图表渲染完成 THEN THE System SHALL 使用淡入动画，提升视觉体验
4. WHEN 图表不在视口内 THEN THE System SHALL 延迟渲染，优先渲染可见图表
5. WHEN 图表渲染失败 THEN THE System SHALL 不阻塞其他图表的渲染
### Requirement 19: Mermaid 错误提示优化
**User Story:** 作为用户，我希望 Mermaid 渲染错误时能看到清晰的错误提示和原始代码。
#### Acceptance Criteria
1. WHEN 图表渲染失败 THEN THE System SHALL 显示友好的错误提示容器
2. WHEN 显示错误提示 THEN THE System SHALL 包含错误类型、错误信息和错误行号
3. WHEN 显示错误提示 THEN THE System SHALL 提供可折叠的原始代码查看区域
4. WHEN 错误提示显示 THEN THE System SHALL 使用醒目的颜色和图标，便于识别
5. WHEN 夜间模式 THEN THE System SHALL 调整错误提示的颜色方案，保持可读性
### Requirement 20: Mermaid 工具栏按钮扩展
**User Story:** 作为用户，我希望 Mermaid 工具栏提供更多实用功能。
#### Acceptance Criteria
1. WHEN 工具栏显示 THEN THE System SHALL 包含缩放、重置、全屏、导出按钮
2. WHEN 鼠标悬停按钮 THEN THE System SHALL 显示按钮功能提示（tooltip）
3. WHEN 按钮不可用时 THEN THE System SHALL 显示禁用状态，避免误操作
4. WHEN 点击按钮 THEN THE System SHALL 提供视觉反馈（按下效果）
5. WHEN 工具栏按钮过多 THEN THE System SHALL 使用下拉菜单收纳次要功能