feat: 实现 Mermaid 库加载等待机制
- 添加 waitForMermaid() 函数，使用 Promise 实现异步等待 - 设置超时机制（默认 5000ms），防止无限等待 - 使用轮询检查库加载状态（每 100ms 检查一次） - 记录加载时间和状态日志，便于调试 - 将 renderAllCharts() 改为 async 函数，渲染前等待库加载 - 将 init() 函数改为 async 函数，使用 waitForMermaid() 替代原来的 setInterval - 添加完整的 JSDoc 注释，说明参数和返回值 - 遵循项目代码规范（Tab 缩进、单引号、严格相等） - 完成任务 2.1
This commit is contained in:
@@ -4798,6 +4798,44 @@ void 0;
|
||||
rendered: new Set(), // 已渲染的图表 ID 集合
|
||||
config: null,
|
||||
|
||||
/**
|
||||
* 等待 Mermaid 库加载
|
||||
* 需求 2.6: 清除缓存后首次加载时等待 Mermaid 库完全加载
|
||||
* 需求 4.1: 开始渲染前检查 Mermaid 库是否已加载
|
||||
* 需求 4.2: Mermaid 库未加载时等待库加载或显示错误提示
|
||||
* @param {number} timeout - 超时时间（毫秒），默认 5000ms
|
||||
* @returns {Promise<boolean>} 是否加载成功
|
||||
*/
|
||||
waitForMermaid(timeout = 5000) {
|
||||
return new Promise((resolve) => {
|
||||
// 如果已经加载，直接返回成功
|
||||
if (typeof window.mermaid !== 'undefined') {
|
||||
this.logDebug('Mermaid 库已加载');
|
||||
resolve(true);
|
||||
return;
|
||||
}
|
||||
|
||||
this.logDebug('Mermaid 库未加载，开始等待...');
|
||||
|
||||
const startTime = Date.now();
|
||||
const checkInterval = setInterval(() => {
|
||||
// 检查是否已加载
|
||||
if (typeof window.mermaid !== 'undefined') {
|
||||
clearInterval(checkInterval);
|
||||
const loadTime = Date.now() - startTime;
|
||||
this.logDebug(`Mermaid 库加载成功，耗时 ${loadTime}ms`);
|
||||
resolve(true);
|
||||
}
|
||||
// 检查是否超时
|
||||
else if (Date.now() - startTime > timeout) {
|
||||
clearInterval(checkInterval);
|
||||
this.logError(`Mermaid 库加载超时（${timeout}ms）`);
|
||||
resolve(false);
|
||||
}
|
||||
}, 100); // 每 100ms 检查一次
|
||||
});
|
||||
},
|
||||
|
||||
/**
|
||||
* 初始化 Mermaid 配置
|
||||
*/
|
||||
@@ -5251,10 +5289,19 @@ void 0;
|
||||
|
||||
/**
|
||||
* 批量渲染所有 Mermaid 图表
|
||||
* 需求 2.6: 清除缓存后首次加载时等待 Mermaid 库完全加载
|
||||
* 需求 4.1: 开始渲染前检查 Mermaid 库是否已加载
|
||||
* 需求 18.1: 使用批量渲染，避免阻塞主线程
|
||||
* 需求 18.4: 延迟渲染视口外的图表，优先渲染可见图表
|
||||
* @returns {Promise<void>}
|
||||
*/
|
||||
renderAllCharts() {
|
||||
async renderAllCharts() {
|
||||
// 需求 4.1-4.2: 等待 Mermaid 库加载
|
||||
if (!await this.waitForMermaid()) {
|
||||
this.logError('Mermaid 库加载失败，无法渲染图表');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!this.initialized) {
|
||||
this.logDebug('Mermaid 未初始化，跳过渲染');
|
||||
return;
|
||||
@@ -6657,32 +6704,18 @@ void 0;
|
||||
|
||||
/**
|
||||
* 初始化渲染引擎
|
||||
* @returns {Promise<void>}
|
||||
*/
|
||||
init() {
|
||||
async init() {
|
||||
// 检查是否启用
|
||||
if (typeof window.argonMermaidConfig !== 'undefined' && !window.argonMermaidConfig.enabled) {
|
||||
this.logDebug('Mermaid 支持未启用');
|
||||
return;
|
||||
}
|
||||
|
||||
// 检查 Mermaid 库是否加载
|
||||
if (typeof window.mermaid === 'undefined') {
|
||||
this.logDebug('Mermaid 库未加载，等待加载...');
|
||||
|
||||
// 等待库加载（最多等待 5 秒）
|
||||
let attempts = 0;
|
||||
const checkInterval = setInterval(() => {
|
||||
attempts++;
|
||||
if (typeof window.mermaid !== 'undefined') {
|
||||
clearInterval(checkInterval);
|
||||
this.logDebug('Mermaid 库加载完成');
|
||||
this.initAndRender();
|
||||
} else if (attempts >= 50) {
|
||||
clearInterval(checkInterval);
|
||||
this.logError('Mermaid 库加载超时');
|
||||
}
|
||||
}, 100);
|
||||
|
||||
// 需求 2.6, 4.1-4.2: 等待 Mermaid 库加载
|
||||
if (!await this.waitForMermaid()) {
|
||||
this.logError('Mermaid 库加载失败');
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
124
tests/test-mermaid-wait-mechanism.md
Normal file
124
tests/test-mermaid-wait-mechanism.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Mermaid 库加载等待机制测试
|
||||
|
||||
## 测试目标
|
||||
验证任务 2.1 的实现：Mermaid 库加载等待机制
|
||||
|
||||
## 实现的功能
|
||||
|
||||
### 1. waitForMermaid() 函数
|
||||
- ✅ 返回 Promise<boolean>
|
||||
- ✅ 检查 Mermaid 库是否已加载
|
||||
- ✅ 如果已加载，立即返回 true
|
||||
- ✅ 如果未加载，使用轮询机制等待（每 100ms 检查一次）
|
||||
- ✅ 设置超时机制（默认 5000ms）
|
||||
- ✅ 超时后返回 false
|
||||
- ✅ 记录加载时间和状态日志
|
||||
|
||||
### 2. 集成到渲染流程
|
||||
- ✅ renderAllCharts() 改为 async 函数
|
||||
- ✅ 渲染前调用 waitForMermaid() 等待库加载
|
||||
- ✅ 库加载失败时记录错误并停止渲染
|
||||
- ✅ init() 函数改为 async 函数
|
||||
- ✅ 初始化时使用 waitForMermaid() 替代原来的 setInterval
|
||||
|
||||
## 测试场景
|
||||
|
||||
### 场景 1: 库已加载
|
||||
**步骤：**
|
||||
1. 确保 Mermaid 库已加载
|
||||
2. 调用 waitForMermaid()
|
||||
3. 验证立即返回 true
|
||||
|
||||
**预期结果：**
|
||||
- 函数立即返回 true
|
||||
- 日志显示 "Mermaid 库已加载"
|
||||
|
||||
### 场景 2: 库延迟加载
|
||||
**步骤：**
|
||||
1. 页面加载时 Mermaid 库未加载
|
||||
2. 调用 waitForMermaid()
|
||||
3. 500ms 后加载 Mermaid 库
|
||||
4. 验证函数等待并返回 true
|
||||
|
||||
**预期结果：**
|
||||
- 函数等待库加载
|
||||
- 库加载后返回 true
|
||||
- 日志显示加载耗时（约 500ms）
|
||||
|
||||
### 场景 3: 库加载超时
|
||||
**步骤：**
|
||||
1. 页面加载时 Mermaid 库未加载
|
||||
2. 调用 waitForMermaid(2000) 设置 2 秒超时
|
||||
3. 2 秒内库未加载
|
||||
4. 验证函数超时返回 false
|
||||
|
||||
**预期结果：**
|
||||
- 函数等待 2 秒后返回 false
|
||||
- 日志显示 "Mermaid 库加载超时（2000ms）"
|
||||
|
||||
### 场景 4: PJAX 页面切换
|
||||
**步骤：**
|
||||
1. 通过 PJAX 跳转到包含 Mermaid 图表的页面
|
||||
2. renderAllCharts() 被调用
|
||||
3. 验证等待库加载后再渲染
|
||||
|
||||
**预期结果：**
|
||||
- 等待库加载完成
|
||||
- 成功渲染所有图表
|
||||
- 不显示原始代码
|
||||
|
||||
## 代码规范检查
|
||||
|
||||
### ✅ JSDoc 注释
|
||||
```javascript
|
||||
/**
|
||||
* 等待 Mermaid 库加载
|
||||
* 需求 2.6: 清除缓存后首次加载时等待 Mermaid 库完全加载
|
||||
* 需求 4.1: 开始渲染前检查 Mermaid 库是否已加载
|
||||
* 需求 4.2: Mermaid 库未加载时等待库加载或显示错误提示
|
||||
* @param {number} timeout - 超时时间（毫秒），默认 5000ms
|
||||
* @returns {Promise<boolean>} 是否加载成功
|
||||
*/
|
||||
```
|
||||
|
||||
### ✅ 代码风格
|
||||
- Tab 缩进
|
||||
- 单引号字符串
|
||||
- 严格相等 (===)
|
||||
- 语句末尾分号
|
||||
- 使用 const/let（不使用 var）
|
||||
|
||||
### ✅ 错误处理
|
||||
- 超时时记录错误日志
|
||||
- 加载失败时停止渲染
|
||||
- 提供友好的错误提示
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 轮询间隔
|
||||
- 每 100ms 检查一次（平衡响应速度和性能）
|
||||
- 避免过于频繁的检查
|
||||
|
||||
### 超时设置
|
||||
- 默认 5000ms（5 秒）
|
||||
- 可自定义超时时间
|
||||
- 防止无限等待
|
||||
|
||||
### 日志记录
|
||||
- 记录加载耗时
|
||||
- 便于性能分析和调试
|
||||
|
||||
## 需求映射
|
||||
|
||||
| 需求 ID | 需求描述 | 实现状态 |
|
||||
|---------|----------|----------|
|
||||
| 2.6 | 清除缓存后首次加载时等待 Mermaid 库完全加载 | ✅ |
|
||||
| 4.1 | 开始渲染前检查 Mermaid 库是否已加载 | ✅ |
|
||||
| 4.2 | Mermaid 库未加载时等待库加载或显示错误提示 | ✅ |
|
||||
|
||||
## 下一步
|
||||
|
||||
任务 2.1 已完成，可以继续：
|
||||
- 任务 2.2: 优化 Mermaid 初始化配置
|
||||
- 任务 2.3: 添加语法错误处理和友好提示
|
||||
- 任务 2.4: 测试各种图表类型
|
||||
Reference in New Issue
Block a user