nanhaoluo
07cd43e2bd
- 验证错误捕获机制完整（同步和异步） - 验证友好错误提示已实现 - 验证原始代码查看功能 - 验证错误类型识别和行号提取 - 验证完整的 CSS 样式（日间/夜间模式） - 创建测试文档和总结文档 - 更新任务状态为已完成 - 满足需求 2.5, 7.1-7.4
258 lines
13 KiB
Markdown
258 lines
13 KiB
Markdown
# Requirements Document: Mermaid 代码块渲染修复
|
||
|
||
## Introduction
|
||
|
||
本规范旨在修复 Argon WordPress 主题中 Mermaid 图表渲染的关键问题。当前实现存在以下严重问题：
|
||
|
||
**核心问题：**
|
||
1. **PJAX 加载后显示原始文本**：点击文章卡片后，Mermaid 图表显示为纯文本，没有任何样式
|
||
2. **语法解析错误**：日志显示 `flowchart`、`erDiagram`、`stateDiagram` 等语法解析失败
|
||
3. **图片导出功能缺失**：无法导出 PNG/SVG 格式的图表
|
||
4. **全屏查看体验差**：全屏查看应该复用图片查看组件，提供统一的交互体验
|
||
|
||
**优化目标：**
|
||
1. 修复 PJAX 页面切换后 Mermaid 图表不渲染的问题
|
||
2. 解决 Mermaid 语法解析错误
|
||
3. 实现图表导出功能（PNG/SVG）
|
||
4. 优化全屏查看体验，复用图片查看组件
|
||
|
||
## Glossary
|
||
|
||
- **PJAX**: 使用 Ajax 和 pushState 实现的页面无刷新跳转技术
|
||
- **Mermaid**: 基于文本的图表生成库，支持流程图、时序图、ER图等
|
||
- **Code Block**: 代码块，包含 Mermaid 图表定义的 HTML 元素
|
||
- **Syntax Error**: 语法错误，Mermaid 解析图表定义时遇到的错误
|
||
- **Render**: 渲染，将 Mermaid 文本定义转换为 SVG 图表
|
||
- **Export**: 导出，将渲染后的图表保存为图片文件
|
||
- **Lightbox**: 图片查看组件，用于全屏查看图片
|
||
- **Zoomify**: 图片缩放库，提供缩放和拖拽功能
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: PJAX 页面切换后 Mermaid 渲染
|
||
|
||
**User Story:** 作为用户，我希望通过 PJAX 跳转到文章页面后，Mermaid 图表能正常渲染，而不是显示原始文本。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户点击文章卡片 THEN THE System SHALL 通过 PJAX 加载新页面
|
||
2. WHEN PJAX 加载完成 THEN THE System SHALL 检测页面中的 Mermaid 代码块
|
||
3. WHEN 检测到 Mermaid 代码块 THEN THE System SHALL 渲染这些代码块为 SVG 图表
|
||
4. WHEN 渲染完成 THEN THE System SHALL 显示图表，而不是原始文本
|
||
5. WHEN 页面刷新后 THEN THE System SHALL 同样能正常渲染 Mermaid 图表
|
||
|
||
### Requirement 2: Mermaid 语法解析错误修复
|
||
|
||
**User Story:** 作为用户，我希望 Mermaid 图表能正确解析各种图表类型，不出现语法错误。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN Mermaid 库加载时 THEN THE System SHALL 检查库版本和 API 兼容性
|
||
2. WHEN 解析 flowchart 语法 THEN THE System SHALL 正确识别并渲染流程图
|
||
3. WHEN 解析 erDiagram 语法 THEN THE System SHALL 正确识别并渲染 ER 图
|
||
4. WHEN 解析 stateDiagram 语法 THEN THE System SHALL 正确识别并渲染状态图
|
||
5. WHEN 遇到语法错误 THEN THE System SHALL 显示友好的错误提示，而不是抛出未捕获的异常
|
||
6. WHEN 清除缓存后首次加载 THEN THE System SHALL 等待 Mermaid 库完全加载后再渲染
|
||
|
||
### Requirement 3: Mermaid 代码块检测
|
||
|
||
**User Story:** 作为开发者，我希望系统能准确检测页面中的 Mermaid 代码块。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 页面加载完成 THEN THE System SHALL 扫描所有 `<pre><code>` 元素
|
||
2. WHEN 检测代码块 THEN THE System SHALL 识别 `language-mermaid` 类名
|
||
3. WHEN 检测代码块 THEN THE System SHALL 识别 `mermaid` 类名
|
||
4. WHEN 检测代码块 THEN THE System SHALL 提取代码块中的 Mermaid 定义文本
|
||
5. WHEN 代码块已渲染 THEN THE System SHALL 跳过该代码块，避免重复渲染
|
||
|
||
### Requirement 4: Mermaid 渲染流程优化
|
||
|
||
**User Story:** 作为开发者，我希望 Mermaid 渲染流程稳定可靠，能处理各种边缘情况。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 开始渲染 THEN THE System SHALL 检查 Mermaid 库是否已加载
|
||
2. WHEN Mermaid 库未加载 THEN THE System SHALL 等待库加载或显示错误提示
|
||
3. WHEN 渲染图表 THEN THE System SHALL 使用唯一的图表 ID，避免冲突
|
||
4. WHEN 渲染成功 THEN THE System SHALL 替换原始代码块为渲染后的容器
|
||
5. WHEN 渲染失败 THEN THE System SHALL 保留原始代码块并显示错误信息
|
||
6. WHEN 渲染多个图表 THEN THE System SHALL 按顺序渲染，避免并发冲突
|
||
|
||
### Requirement 5: 图表导出功能
|
||
|
||
**User Story:** 作为用户，我希望能将 Mermaid 图表导出为图片文件，方便保存和分享。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 鼠标悬停在图表上 THEN THE System SHALL 显示工具栏
|
||
2. WHEN 工具栏显示 THEN THE System SHALL 包含导出按钮
|
||
3. WHEN 点击导出按钮 THEN THE System SHALL 显示导出选项（PNG、SVG）
|
||
4. WHEN 选择 PNG 导出 THEN THE System SHALL 将 SVG 转换为 PNG 并下载
|
||
5. WHEN 选择 SVG 导出 THEN THE System SHALL 将 SVG 代码保存为文件并下载
|
||
6. WHEN 导出失败 THEN THE System SHALL 显示友好的错误提示
|
||
|
||
### Requirement 6: 全屏查看功能优化
|
||
|
||
**User Story:** 作为用户，我希望全屏查看 Mermaid 图表时，能获得与查看图片相同的体验。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 工具栏显示 THEN THE System SHALL 包含全屏按钮
|
||
2. WHEN 点击全屏按钮 THEN THE System SHALL 使用图片查看组件（Zoomify）打开图表
|
||
3. WHEN 全屏模式下 THEN THE System SHALL 支持缩放、拖拽、旋转等操作
|
||
4. WHEN 全屏模式下 THEN THE System SHALL 支持键盘快捷键（ESC 退出、方向键切换）
|
||
5. WHEN 退出全屏 THEN THE System SHALL 恢复原始页面状态
|
||
|
||
### Requirement 7: 错误处理和降级
|
||
|
||
**User Story:** 作为开发者，我希望系统能优雅地处理各种错误情况。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN Mermaid 库加载失败 THEN THE System SHALL 显示错误提示并保留原始代码
|
||
2. WHEN 图表语法错误 THEN THE System SHALL 显示错误信息和错误位置
|
||
3. WHEN 渲染超时 THEN THE System SHALL 取消渲染并显示超时提示
|
||
4. WHEN 浏览器不支持 SVG THEN THE System SHALL 显示不支持提示
|
||
5. WHEN 导出功能不可用 THEN THE System SHALL 隐藏导出按钮
|
||
|
||
### Requirement 8: 性能优化
|
||
|
||
**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 PJAX 切换页面 THEN THE System SHALL 清理旧图表实例，避免内存泄漏
|
||
|
||
### Requirement 9: 主题同步
|
||
|
||
**User Story:** 作为用户，我希望 Mermaid 图表主题能自动跟随网站主题切换。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 网站使用日间模式 THEN THE System SHALL 使用 Mermaid 的 default 主题
|
||
2. WHEN 网站切换到夜间模式 THEN THE System SHALL 自动切换 Mermaid 到 dark 主题
|
||
3. WHEN 主题切换时 THEN THE System SHALL 重新渲染所有图表
|
||
4. WHEN 主题切换时 THEN THE System SHALL 保持图表的缩放级别和位置
|
||
5. WHEN 主题切换失败 THEN THE System SHALL 保留原主题，不影响图表显示
|
||
|
||
### Requirement 10: 响应式设计
|
||
|
||
**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 11: 交互体验优化
|
||
|
||
**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 显示按钮功能提示（tooltip）
|
||
5. WHEN 点击按钮 THEN THE System SHALL 提供视觉反馈（按下效果、加载动画）
|
||
6. WHEN 操作失败 THEN THE System SHALL 显示友好的错误提示
|
||
7. WHEN 图表加载中 THEN THE System SHALL 显示加载动画，避免空白闪烁
|
||
|
||
### Requirement 12: 缩放和拖拽功能
|
||
|
||
**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 智能缩放到合适大小
|
||
6. WHEN 拖拽图表 THEN THE System SHALL 改变鼠标光标为抓手样式
|
||
7. WHEN 拖拽时 THEN THE System SHALL 禁用文本选择，避免误选
|
||
8. WHEN 图表未缩放且完全可见 THEN THE System SHALL 禁用拖拽功能
|
||
|
||
### Requirement 13: 代码质量保证
|
||
|
||
**User Story:** 作为开发者，我希望代码质量高，易于维护和扩展。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 编写代码 THEN THE System SHALL 遵循项目代码规范（Tab 缩进、单引号等）
|
||
2. WHEN 定义函数 THEN THE System SHALL 添加 JSDoc 注释，说明参数和返回值
|
||
3. WHEN 使用变量 THEN THE System SHALL 优先使用 let 和 const，避免 var
|
||
4. WHEN 处理异步操作 THEN THE System SHALL 使用 async/await 或 Promise
|
||
5. WHEN 添加事件监听器 THEN THE System SHALL 确保在清理时移除监听器
|
||
6. WHEN 操作 DOM THEN THE System SHALL 批量操作，避免频繁重排重绘
|
||
7. WHEN 使用第三方库 THEN THE System SHALL 检查库是否存在，提供降级方案
|
||
|
||
### Requirement 14: 错误日志和调试
|
||
|
||
**User Story:** 作为开发者，我希望能方便地调试和排查问题。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 启用调试模式 THEN THE System SHALL 在控制台输出详细的渲染日志
|
||
2. WHEN 渲染开始 THEN THE System SHALL 记录图表 ID、代码长度、渲染时间
|
||
3. WHEN 渲染成功 THEN THE System SHALL 记录成功信息和渲染耗时
|
||
4. WHEN 渲染失败 THEN THE System SHALL 记录错误类型、错误信息、错误堆栈
|
||
5. WHEN 发生异常 THEN THE System SHALL 记录上下文信息（图表代码、配置等）
|
||
6. WHEN 性能异常 THEN THE System SHALL 记录性能指标（渲染时间、内存占用）
|
||
|
||
### Requirement 15: 兼容性保证
|
||
|
||
**User Story:** 作为用户，我希望功能在不同浏览器和设备上都能正常工作。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 浏览器不支持 Promise THEN THE System SHALL 使用回调函数实现异步逻辑
|
||
2. WHEN 浏览器不支持 requestAnimationFrame THEN THE System SHALL 使用 setTimeout 降级
|
||
3. WHEN 浏览器不支持 SVG THEN THE System SHALL 显示不支持提示
|
||
4. WHEN 移动端浏览器 THEN THE System SHALL 优化触摸事件处理
|
||
5. WHEN 旧版浏览器 THEN THE System SHALL 提供 polyfill 或禁用高级功能
|
||
|
||
### Requirement 16: 内存管理
|
||
|
||
**User Story:** 作为开发者，我希望系统能正确管理内存，避免内存泄漏。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN PJAX 切换页面 THEN THE System SHALL 清理所有 Mermaid 实例
|
||
2. WHEN 清理实例 THEN THE System SHALL 移除所有事件监听器
|
||
3. WHEN 清理实例 THEN THE System SHALL 移除所有 DOM 引用
|
||
4. WHEN 清理实例 THEN THE System SHALL 清空图表缓存
|
||
5. WHEN 重新渲染 THEN THE System SHALL 先清理旧实例，再创建新实例
|
||
|
||
### Requirement 17: 配置和扩展性
|
||
|
||
**User Story:** 作为开发者，我希望系统配置灵活，易于扩展。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 初始化 Mermaid THEN THE System SHALL 从全局配置读取主题设置
|
||
2. WHEN 配置改变 THEN THE System SHALL 支持动态更新配置
|
||
3. WHEN 添加新功能 THEN THE System SHALL 使用模块化设计，易于扩展
|
||
4. WHEN 自定义主题 THEN THE System SHALL 支持自定义 Mermaid 主题配置
|
||
5. WHEN 禁用功能 THEN THE System SHALL 支持通过配置禁用特定功能
|
||
|
||
### Requirement 18: 安全性
|
||
|
||
**User Story:** 作为开发者，我希望系统能防止 XSS 攻击和其他安全问题。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 渲染图表 THEN THE System SHALL 使用 Mermaid 的安全模式（securityLevel）
|
||
2. WHEN 处理用户输入 THEN THE System SHALL 转义特殊字符，防止 XSS
|
||
3. WHEN 导出图表 THEN THE System SHALL 验证文件名，防止路径遍历
|
||
4. WHEN 执行脚本 THEN THE System SHALL 使用沙箱环境，限制权限
|
||
5. WHEN 加载外部资源 THEN THE System SHALL 验证来源，防止 CSRF
|