nanhaoluo/argon-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
43b695bd66048529240756367d5a82ffa800ba80
argon-theme/.kiro/specs/mermaid-support/tasks.md
nanhaoluo 43b695bd66 feat: 实现 Mermaid JavaScript 渲染引擎 
- 在 argontheme.js 中添加完整的 Mermaid 渲染引擎模块
- 实现 Mermaid 配置初始化函数（支持主题自动切换）
- 实现主题获取函数（根据页面 darkmode 类返回对应主题）
- 实现代码块检测器（支持 div.mermaid、pre code.language-mermaid、pre[data-lang]、code.mermaid 四种格式）
- 实现批量渲染函数（一次 DOM 遍历，批量渲染所有图表）
- 实现错误处理机制（显示友好错误提示，保留原始代码）
- 实现样式增强（淡入动画、响应式 SVG）
- 实现主题切换监听器（监听 argon:theme-switched 事件和 darkmode class 变化）
- 实现图表重新渲染功能（主题切换时自动重新渲染）
- 实现渲染缓存机制（避免重复渲染）
- 添加调试日志系统（支持 debugMode 配置）
- 在 DOMContentLoaded 事件中自动初始化
- 暴露 ArgonMermaidRenderer 到全局（用于 PJAX 等场景）
- Requirements: 2.1, 2.5, 10.1, 10.2, 10.3
2026-01-23 23:02:25 +08:00

8.6 KiB
Raw Blame History

Implementation Plan: Mermaid 图表支持

Overview

本实施计划将 Mermaid 图表支持功能集成到 Argon WordPress 主题中。采用插件兼容方案，主题提供样式增强、主题适配和性能优化。实施过程分为配置管理、库加载、渲染引擎、样式优化和测试验证五个阶段。

Tasks

  • 1. 创建配置管理系统

    • 在 functions.php 中添加 Mermaid 配置管理函数
    • 实现配置选项的获取、保存和验证功能
    • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5

  • * 1.1 编写配置管理函数的单元测试

    • 测试配置选项的获取和保存
    • 测试 CDN URL 验证逻辑
    • 测试默认值处理
    • Requirements: 5.5

  • 2. 在设置页添加 Mermaid 配置选项

    • 在 settings.php 中创建新的设置分类"Mermaid 图表"
    • 添加启用/禁用开关
    • 添加 CDN 来源选择（jsDelivr、unpkg、自定义、本地）
    • 添加自定义 CDN 地址输入框
    • 添加图表主题选择（default、dark、forest、neutral、auto）
    • 添加本地镜像开关
    • 添加调试模式开关
    • Requirements: 5.1, 5.2, 5.3, 5.4

  • 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

  • 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

  • [~] 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

  • [~] 6. Checkpoint - 基础功能验证

    • 确保所有测试通过
    • 在测试环境中验证基础渲染功能
    • 测试不同类型的 Mermaid 图表（流程图、时序图、类图）
    • 如有问题，询问用户

  • [~] 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

  • [~] 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

  • [~] 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

  • [~] 10. 添加性能优化

    • 实现渲染缓存机制（避免重复渲染）
    • 优化批量渲染逻辑
    • 添加渲染状态标记
    • Requirements: 8.3, 8.4

  • * 10.1 编写渲染缓存的属性测试

    • Property 16: 渲染缓存 - 对于任意已渲染的图表，不应该重复渲染
    • Validates: Requirements 8.3
    • Requirements: 8.3

  • [~] 11. 添加特殊格式处理

    • 处理 WP-Markdown 生成的 <script>document.write()</script> 格式
    • 实现转义字符解码（\n, \", \'）
    • 添加注释代码块过滤
    • Requirements: 10.5

  • * 11.1 编写注释代码块过滤的属性测试

    • Property 18: 忽略注释代码块 - 对于任意被注释包裹的代码块，应该忽略
    • Validates: Requirements 10.5
    • Requirements: 10.5

  • [~] 12. Checkpoint - 完整功能验证

    • 确保所有测试通过
    • 测试所有配置选项
    • 测试主题切换功能
    • 测试错误处理
    • 测试插件兼容性
    • 如有问题，询问用户

  • [~] 13. 添加设置页预览功能

    • 在设置页添加 Mermaid 预览区域
    • 实现实时预览功能
    • 添加示例图表代码
    • Requirements: 5.6

  • [~] 14. 编写文档和注释

    • 为所有函数添加 PHPDoc 和 JSDoc 注释
    • 在设置页添加使用说明
    • 创建用户文档（如何使用 Mermaid）
    • 添加常见问题解答

  • * 15. 集成测试

    • 测试完整的渲染流程
    • 测试与 WP Githuber MD 插件的集成
    • 测试与 Markdown Block 插件的集成
    • 测试主题切换时的重新渲染
    • 测试 CDN 加载失败的降级处理
    • Requirements: 9.1, 9.2, 9.3

  • [~] 16. 最终验证和优化

    • 运行所有单元测试和属性测试
    • 检查代码覆盖率（PHP ≥80%，JS ≥85%）
    • 进行性能测试（页面加载时间、渲染速度）
    • 进行浏览器兼容性测试
    • 优化代码和注释

  • [~] 17. 手动测试清单

    • 验证图表颜色与页面背景色的对比度
    • 验证图表容器样式与主题整体风格的一致性
    • 测试所有 Mermaid 官方图表类型
    • 测试移动端显示效果
    • 验证错误提示信息的友好性
    • 测试设置页预览功能

Notes

  • 任务标记 * 的为可选测试任务，可以跳过以加快 MVP 开发
  • 每个任务都引用了具体的需求编号，确保可追溯性
  • Checkpoint 任务用于增量验证，确保功能正确性
  • 属性测试验证通用正确性属性
  • 单元测试验证具体示例和边缘情况
  • 集成测试验证端到端流程
Reference in New Issue View Git Blame Copy Permalink