nanhaoluo
29bfd284e0
- 添加 convertMermaidCodeblocks() 函数，在代码高亮前拦截 mermaid 代码块 - 支持标准 Markdown 代码块 (\\\mermaid) 渲染 - 更新 detectMermaidBlocks() 添加 mermaid-from-codeblock 选择器 - 更新 extractMermaidCode() 支持新容器类型 - 创建测试文件 test-codeblock-magic.html - 更新用户文档、开发者文档和 FAQ - 完全绕过代码高亮和 WordPress 格式化 - 支持 PJAX 页面切换 - 特殊字符和换行符正确保留
227 lines
8.6 KiB
Markdown
227 lines
8.6 KiB
Markdown
# Implementation Plan: Mermaid 图表支持
|
||
|
||
## Overview
|
||
|
||
本实施计划将 Mermaid 图表支持功能集成到 Argon WordPress 主题中。采用插件兼容方案，主题提供样式增强、主题适配和性能优化。实施过程分为配置管理、库加载、渲染引擎、样式优化和测试验证五个阶段。
|
||
|
||
## Tasks
|
||
|
||
- [x] 1. 创建配置管理系统
|
||
- 在 `functions.php` 中添加 Mermaid 配置管理函数
|
||
- 实现配置选项的获取、保存和验证功能
|
||
- _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_
|
||
|
||
- [ ]* 1.1 编写配置管理函数的单元测试
|
||
- 测试配置选项的获取和保存
|
||
- 测试 CDN URL 验证逻辑
|
||
- 测试默认值处理
|
||
- _Requirements: 5.5_
|
||
|
||
- [x] 2. 在设置页添加 Mermaid 配置选项
|
||
- 在 `settings.php` 中创建新的设置分类"Mermaid 图表"
|
||
- 添加启用/禁用开关
|
||
- 添加 CDN 来源选择（jsDelivr、unpkg、自定义、本地）
|
||
- 添加自定义 CDN 地址输入框
|
||
- 添加图表主题选择（default、dark、forest、neutral、auto）
|
||
- 添加本地镜像开关
|
||
- 添加调试模式开关
|
||
- _Requirements: 5.1, 5.2, 5.3, 5.4_
|
||
|
||
- [x] 3. 实现库加载器
|
||
- 在 `functions.php` 中添加页面内容检测函数
|
||
- 实现 Mermaid 代码块检测逻辑（正则表达式）
|
||
- 添加 `wp_enqueue_scripts` 钩子函数
|
||
- 根据配置选择 CDN 或本地加载
|
||
- 实现异步加载（async 属性）
|
||
- _Requirements: 1.1, 1.2, 1.3, 1.5, 8.2_
|
||
|
||
- [ ]* 3.1 编写库加载器的属性测试
|
||
- **Property 1: 按需加载库** - 对于任意页面，当且仅当包含 Mermaid 代码块时加载库
|
||
- **Validates: Requirements 1.1, 1.5**
|
||
- _Requirements: 1.1, 1.5_
|
||
|
||
- [ ]* 3.2 编写 CDN 地址正确性的属性测试
|
||
- **Property 2: CDN 地址正确性** - 对于任意 CDN 配置选项，生成的 URL 应该匹配
|
||
- **Validates: Requirements 1.2, 1.3**
|
||
- _Requirements: 1.2, 1.3_
|
||
|
||
- [x] 4. 创建 JavaScript 渲染引擎
|
||
- 在 `argontheme.js` 或新建 `argon-mermaid.js` 文件
|
||
- 实现 Mermaid 配置初始化函数
|
||
- 实现主题获取函数（根据页面模式返回对应主题）
|
||
- 实现代码块检测器（支持多种格式）
|
||
- 实现批量渲染函数
|
||
- 添加 DOMContentLoaded 事件监听
|
||
- _Requirements: 2.1, 2.5, 10.1, 10.2, 10.3_
|
||
|
||
- [ ]* 4.1 编写代码块识别的属性测试
|
||
- **Property 3: 代码块识别完整性** - 对于任意包含 Mermaid 标记的元素，应该能够识别
|
||
- **Validates: Requirements 10.1, 10.2, 10.3**
|
||
- _Requirements: 10.1, 10.2, 10.3_
|
||
|
||
- [ ]* 4.2 编写代码块优先级的属性测试
|
||
- **Property 17: 代码块优先级** - 对于同时包含多个标记的元素，优先使用 class 属性
|
||
- **Validates: Requirements 10.4**
|
||
- _Requirements: 10.4_
|
||
|
||
- [ ]* 4.3 编写批量渲染性能的属性测试
|
||
- **Property 15: 批量渲染性能** - 对于任意包含多个图表的页面，应该批量渲染
|
||
- **Validates: Requirements 8.4**
|
||
- _Requirements: 8.4_
|
||
|
||
- [x] 5. 实现错误处理机制
|
||
- 添加库加载失败的降级处理（多个 CDN 备选）
|
||
- 实现代码解析错误的捕获和显示
|
||
- 创建错误提示 UI 组件
|
||
- 添加调试模式日志输出
|
||
- 保留原始代码块供用户查看
|
||
- _Requirements: 1.4, 2.3, 7.1, 7.2, 7.3, 7.4, 7.5_
|
||
|
||
- [ ]* 5.1 编写错误处理的属性测试
|
||
- **Property 5: 错误时保留原始代码** - 对于任意渲染失败的代码块，应该保留原始代码
|
||
- **Validates: Requirements 7.1, 7.4**
|
||
- _Requirements: 7.1, 7.4_
|
||
|
||
- [ ]* 5.2 编写错误信息完整性的属性测试
|
||
- **Property 14: 错误信息完整性** - 对于任意解析错误，应该包含错误类型和详细描述
|
||
- **Validates: Requirements 7.3**
|
||
- _Requirements: 7.3_
|
||
|
||
- [x] 6. Checkpoint - 基础功能验证
|
||
- 确保所有测试通过
|
||
- 在测试环境中验证基础渲染功能
|
||
- 测试不同类型的 Mermaid 图表（流程图、时序图、类图）
|
||
- 如有问题，询问用户
|
||
|
||
- [x] 7. 添加样式增强
|
||
- 在 `style.css` 中添加 Mermaid 容器样式
|
||
- 实现响应式设计（max-width: 100%，overflow-x: auto）
|
||
- 添加夜间模式样式适配
|
||
- 添加卡片内边距样式
|
||
- 添加淡入动画效果
|
||
- _Requirements: 3.1, 3.3, 6.1, 6.3, 6.4, 6.5_
|
||
|
||
- [ ]* 7.1 编写响应式样式的属性测试
|
||
- **Property 8: 响应式容器宽度** - 对于任意图表容器，最大宽度应为 100%
|
||
- **Validates: Requirements 3.1, 3.3**
|
||
- _Requirements: 3.1, 3.3_
|
||
|
||
- [ ]* 7.2 编写移动端适配的属性测试
|
||
- **Property 9: 移动端自适应** - 对于任意小屏幕设备，图表应该自适应
|
||
- **Validates: Requirements 3.2**
|
||
- _Requirements: 3.2_
|
||
|
||
- [ ]* 7.3 编写夜间模式样式的属性测试
|
||
- **Property 10: 夜间模式样式适配** - 对于任意图表容器，夜间模式下应该应用深色样式
|
||
- **Validates: Requirements 6.5**
|
||
- _Requirements: 6.5_
|
||
|
||
- [ ]* 7.4 编写卡片内边距的属性测试
|
||
- **Property 11: 卡片内边距** - 对于任意在卡片中的图表，应该添加内边距
|
||
- **Validates: Requirements 6.3**
|
||
- _Requirements: 6.3_
|
||
|
||
- [x] 8. 实现主题切换功能
|
||
- 添加主题切换事件监听器
|
||
- 实现图表重新渲染函数
|
||
- 处理自定义主题优先级
|
||
- 添加防抖优化避免频繁渲染
|
||
- _Requirements: 4.1, 4.2, 4.3, 4.5_
|
||
|
||
- [ ]* 8.1 编写主题切换的属性测试
|
||
- **Property 6: 主题模式自动切换** - 对于任意主题切换，图表应该重新渲染并使用对应主题
|
||
- **Validates: Requirements 4.1, 4.2, 4.3**
|
||
- _Requirements: 4.1, 4.2, 4.3_
|
||
|
||
- [ ]* 8.2 编写自定义主题优先级的属性测试
|
||
- **Property 7: 自定义主题优先级** - 对于任意图表，自定义主题应该优先于自动切换
|
||
- **Validates: Requirements 4.5**
|
||
- _Requirements: 4.5_
|
||
|
||
- [x] 9. 实现插件兼容层
|
||
- 添加插件检测函数（WP Githuber MD、Markdown Block、Code Syntax Block）
|
||
- 实现 Mermaid 库加载状态检测
|
||
- 添加重复加载防护逻辑
|
||
- 在设置页显示插件兼容性状态
|
||
- _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5_
|
||
|
||
- [ ]* 9.1 编写避免重复加载的属性测试
|
||
- **Property 13: 避免重复加载** - 对于任意页面，当检测到已加载库时，不应该重复加载
|
||
- **Validates: Requirements 9.4**
|
||
- _Requirements: 9.4_
|
||
|
||
- [x] 10. 添加性能优化
|
||
- 实现渲染缓存机制（避免重复渲染）
|
||
- 优化批量渲染逻辑
|
||
- 添加渲染状态标记
|
||
- _Requirements: 8.3, 8.4_
|
||
|
||
- [ ]* 10.1 编写渲染缓存的属性测试
|
||
- **Property 16: 渲染缓存** - 对于任意已渲染的图表，不应该重复渲染
|
||
- **Validates: Requirements 8.3**
|
||
- _Requirements: 8.3_
|
||
|
||
- [x] 11. 添加特殊格式处理
|
||
- 处理 WP-Markdown 生成的 `<script>document.write()</script>` 格式
|
||
- 实现转义字符解码（`\n`, `\"`, `\'`）
|
||
- 添加注释代码块过滤
|
||
- _Requirements: 10.5_
|
||
|
||
- [ ]* 11.1 编写注释代码块过滤的属性测试
|
||
- **Property 18: 忽略注释代码块** - 对于任意被注释包裹的代码块，应该忽略
|
||
- **Validates: Requirements 10.5**
|
||
- _Requirements: 10.5_
|
||
|
||
- [x] 12. Checkpoint - 完整功能验证
|
||
- 确保所有测试通过
|
||
- 测试所有配置选项
|
||
- 测试主题切换功能
|
||
- 测试错误处理
|
||
- 测试插件兼容性
|
||
- 如有问题，询问用户
|
||
|
||
- [x] 13. 添加设置页预览功能
|
||
- 在设置页添加 Mermaid 预览区域
|
||
- 实现实时预览功能
|
||
- 添加示例图表代码
|
||
- _Requirements: 5.6_
|
||
|
||
- [x] 14. 编写文档和注释
|
||
- 为所有函数添加 PHPDoc 和 JSDoc 注释
|
||
- 在设置页添加使用说明
|
||
- 创建用户文档（如何使用 Mermaid）
|
||
- 添加常见问题解答
|
||
|
||
- [ ]* 15. 集成测试
|
||
- 测试完整的渲染流程
|
||
- 测试与 WP Githuber MD 插件的集成
|
||
- 测试与 Markdown Block 插件的集成
|
||
- 测试主题切换时的重新渲染
|
||
- 测试 CDN 加载失败的降级处理
|
||
- _Requirements: 9.1, 9.2, 9.3_
|
||
|
||
- [x] 16. 最终验证和优化
|
||
- 运行所有单元测试和属性测试
|
||
- 检查代码覆盖率（PHP ≥80%，JS ≥85%）
|
||
- 进行性能测试（页面加载时间、渲染速度）
|
||
- 进行浏览器兼容性测试
|
||
- 优化代码和注释
|
||
|
||
- [x] 17. 手动测试清单
|
||
- 验证图表颜色与页面背景色的对比度
|
||
- 验证图表容器样式与主题整体风格的一致性
|
||
- 测试所有 Mermaid 官方图表类型
|
||
- 测试移动端显示效果
|
||
- 验证错误提示信息的友好性
|
||
- 测试设置页预览功能
|
||
|
||
## Notes
|
||
|
||
- 任务标记 `*` 的为可选测试任务，可以跳过以加快 MVP 开发
|
||
- 每个任务都引用了具体的需求编号，确保可追溯性
|
||
- Checkpoint 任务用于增量验证，确保功能正确性
|
||
- 属性测试验证通用正确性属性
|
||
- 单元测试验证具体示例和边缘情况
|
||
- 集成测试验证端到端流程
|
||
|