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