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