nanhaoluo
1d5899ce7e
- 添加多 CDN 备选方案（jsdelivr、unpkg、本地镜像） - 实现递归加载逻辑，主 CDN 失败时自动尝试备用 CDN - 添加 onerror 事件处理，捕获库加载失败 - 所有 CDN 失败时显示友好的错误提示 - 在错误提示中保留原始代码供用户查看 - 添加详细的控制台日志输出 - 创建 PHP 和 HTML 测试文件验证功能 - 暴露 MermaidRenderer 到全局作用域供降级处理使用 Requirements: 1.4, 2.3, 7.1, 7.2, 7.3, 7.4, 7.5
7.2 KiB
7.2 KiB
Requirements Document
Introduction
本文档定义了在 Argon WordPress 主题中实现 Mermaid 图表支持功能的需求。Mermaid 是一个基于 JavaScript 的图表和流程图生成工具，允许用户通过文本描述创建各种类型的可视化图表。
由于 WP-Markdown 编辑器的特殊渲染方式（将整个 Mermaid 代码块保存为单行，没有真正的换行符），直接集成 Mermaid 存在技术障碍。本需求文档采用插件集成方案，通过支持 Mermaid 的 WordPress 插件来实现功能。
Glossary
- Mermaid: 基于 JavaScript 的图表生成库，支持流程图、时序图、类图等多种图表类型
- WP-Markdown: WordPress Markdown 编辑器，用于在 WordPress 中编辑 Markdown 格式的内容
- Theme: Argon WordPress 主题系统
- Admin: WordPress 后台管理员
- CDN: 内容分发网络，用于加载外部 JavaScript 库
- Render_Engine: Mermaid 图表渲染引擎
- Code_Block: Markdown 代码块，用于包含 Mermaid 图表定义
- Theme_Mode: 主题模式，包括日间模式和夜间模式
- Settings_Page: Argon 主题设置页面
Requirements
Requirement 1: Mermaid 库加载
User Story: 作为开发者，我希望主题能够正确加载 Mermaid 库，以便在文章中渲染图表。
Acceptance Criteria
- WHEN Admin 在设置页启用 Mermaid 支持 THEN THE Theme SHALL 在前端页面加载 Mermaid JavaScript 库
- WHERE CDN 模式被选择 WHEN 页面加载时 THEN THE Theme SHALL 从指定的 CDN 地址加载 Mermaid 库
- WHERE 本地镜像模式被选择 WHEN 页面加载时 THEN THE Theme SHALL 从主题目录加载本地 Mermaid 库文件
- WHEN Mermaid 库加载失败 THEN THE Theme SHALL 在控制台输出错误信息并降级到备用 CDN
- THE Theme SHALL 仅在包含 Mermaid 代码块的页面加载 Mermaid 库
Requirement 2: 图表渲染
User Story: 作为内容创作者，我希望在文章中使用 Mermaid 语法创建图表，并在前端正确显示。
Acceptance Criteria
- WHEN 文章包含 Mermaid 代码块 THEN THE Render_Engine SHALL 将代码块渲染为可视化图表
- THE Render_Engine SHALL 支持所有 Mermaid 官方图表类型（流程图、时序图、类图、状态图、甘特图、饼图、Git 图等）
- WHEN Mermaid 代码语法错误 THEN THE Render_Engine SHALL 显示友好的错误提示信息
- WHEN 图表渲染成功 THEN THE Theme SHALL 移除原始代码块文本并显示渲染后的 SVG 图表
- THE Render_Engine SHALL 在 DOM 加载完成后初始化并渲染所有图表
Requirement 3: 响应式设计
User Story: 作为用户，我希望图表能够在不同设备上正确显示，以便在移动端也能查看。
Acceptance Criteria
- WHEN 图表宽度超过容器宽度 THEN THE Theme SHALL 启用横向滚动功能
- WHEN 用户在移动设备上查看 THEN THE Theme SHALL 自动调整图表大小以适应屏幕宽度
- THE Theme SHALL 为图表容器设置最大宽度为 100%
- WHEN 图表高度超过视口高度 THEN THE Theme SHALL 保持图表完整性不进行裁剪
- THE Theme SHALL 在图表容器上应用响应式 CSS 样式
Requirement 4: 主题模式适配
User Story: 作为用户，我希望图表能够适配夜间模式，以便在不同主题下都有良好的视觉效果。
Acceptance Criteria
- WHEN 用户切换到夜间模式 THEN THE Theme SHALL 自动切换 Mermaid 图表主题为深色主题
- WHEN 用户切换到日间模式 THEN THE Theme SHALL 自动切换 Mermaid 图表主题为浅色主题
- THE Theme SHALL 在主题切换时重新渲染所有 Mermaid 图表
- THE Theme SHALL 确保图表颜色与页面背景色有足够的对比度
- WHERE Admin 设置了自定义图表主题 THEN THE Theme SHALL 使用自定义主题而不是自动切换
Requirement 5: 后台设置
User Story: 作为管理员，我希望能够在后台配置 Mermaid 功能，以便根据需求调整行为。
Acceptance Criteria
- THE Settings_Page SHALL 提供启用或禁用 Mermaid 支持的开关选项
- THE Settings_Page SHALL 提供 CDN 地址选择选项（jsDelivr、unpkg、自定义）
- THE Settings_Page SHALL 提供图表主题选择选项（default、dark、forest、neutral）
- THE Settings_Page SHALL 提供本地镜像开关选项
- WHEN Admin 保存设置 THEN THE Theme SHALL 验证 CDN 地址格式的有效性
- THE Settings_Page SHALL 提供 Mermaid 配置预览功能
Requirement 6: 样式优化
User Story: 作为内容创作者，我希望图表有美观的样式，以便提升文章的视觉质量。
Acceptance Criteria
- THE Theme SHALL 为图表容器添加背景色、圆角和阴影样式
- THE Theme SHALL 确保图表容器样式与主题整体风格一致
- WHEN 图表在卡片中显示 THEN THE Theme SHALL 添加适当的内边距
- THE Theme SHALL 为图表添加淡入动画效果
- THE Theme SHALL 在夜间模式下调整图表容器的背景色和边框色
Requirement 7: 错误处理
User Story: 作为开发者，我希望系统能够优雅地处理错误，以便快速定位和解决问题。
Acceptance Criteria
- WHEN Mermaid 代码解析失败 THEN THE Theme SHALL 在图表位置显示错误提示信息
- WHEN Mermaid 库加载失败 THEN THE Theme SHALL 在控制台输出详细的错误日志
- THE Theme SHALL 在错误提示中包含错误类型和行号信息
- WHEN 发生错误 THEN THE Theme SHALL 保留原始代码块以便用户修正
- THE Theme SHALL 提供调试模式选项以输出详细的渲染过程信息
Requirement 8: 性能优化
User Story: 作为用户，我希望图表加载不影响页面性能，以便获得流畅的浏览体验。
Acceptance Criteria
- THE Theme SHALL 仅在包含 Mermaid 代码块的页面加载 Mermaid 库
- THE Theme SHALL 使用异步方式加载 Mermaid 库
- THE Theme SHALL 缓存已渲染的图表以避免重复渲染
- WHEN 页面包含多个图表 THEN THE Theme SHALL 批量渲染以提高性能
- THE Theme SHALL 使用 CDN 加速 Mermaid 库的加载速度
Requirement 9: 插件兼容性
User Story: 作为管理员，我希望 Mermaid 功能能够与常用的 WordPress 插件兼容，以便灵活选择编辑器。
Acceptance Criteria
- THE Theme SHALL 支持通过 WP Githuber MD 插件创建的 Mermaid 图表
- THE Theme SHALL 支持通过 Markdown Block 插件创建的 Mermaid 图表
- THE Theme SHALL 支持通过 Code Syntax Block 插件创建的 Mermaid 图表
- WHEN 检测到多个 Mermaid 插件 THEN THE Theme SHALL 避免重复加载 Mermaid 库
- THE Theme SHALL 提供插件兼容性检测功能
Requirement 10: 代码块识别
User Story: 作为开发者，我希望系统能够准确识别 Mermaid 代码块，以便正确渲染图表。
Acceptance Criteria
- THE Theme SHALL 识别 class 属性为 "mermaid" 的 div 元素作为 Mermaid 代码块
- THE Theme SHALL 识别 language 属性为 "mermaid" 的 pre 或 code 元素作为 Mermaid 代码块
- THE Theme SHALL 识别 data-lang 属性为 "mermaid" 的元素作为 Mermaid 代码块
- WHEN 代码块同时包含多个识别标记 THEN THE Theme SHALL 优先使用 class 属性
- THE Theme SHALL 忽略被注释掉的 Mermaid 代码块