From 2fa1948501cde0cb31b4449ac4ff4a4e1bb48766 Mon Sep 17 00:00:00 2001 From: nanhaoluo <3075912108@qq.com> Date: Sun, 25 Jan 2026 13:09:42 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=9E=E7=8E=B0=20Mermaid=20?= =?UTF-8?q?=E5=BA=93=E5=8A=A0=E8=BD=BD=E7=AD=89=E5=BE=85=E6=9C=BA=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加 waitForMermaid() 函数，使用 Promise 实现异步等待 - 设置超时机制（默认 5000ms），防止无限等待 - 使用轮询检查库加载状态（每 100ms 检查一次） - 记录加载时间和状态日志，便于调试 - 将 renderAllCharts() 改为 async 函数，渲染前等待库加载 - 将 init() 函数改为 async 函数，使用 waitForMermaid() 替代原来的 setInterval - 添加完整的 JSDoc 注释，说明参数和返回值 - 遵循项目代码规范（Tab 缩进、单引号、严格相等） - 完成任务 2.1 --- argontheme.js | 73 +++++++++++----- tests/test-mermaid-wait-mechanism.md | 124 +++++++++++++++++++++++++++ 2 files changed, 177 insertions(+), 20 deletions(-) create mode 100644 tests/test-mermaid-wait-mechanism.md diff --git a/argontheme.js b/argontheme.js index 0bc477f..7b27060 100644 --- a/argontheme.js +++ b/argontheme.js @@ -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} 是否加载成功 + */ + 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} */ - 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} */ - 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; } diff --git a/tests/test-mermaid-wait-mechanism.md b/tests/test-mermaid-wait-mechanism.md new file mode 100644 index 0000000..372f050 --- /dev/null +++ b/tests/test-mermaid-wait-mechanism.md @@ -0,0 +1,124 @@ +# Mermaid 库加载等待机制测试 + +## 测试目标 +验证任务 2.1 的实现：Mermaid 库加载等待机制 + +## 实现的功能 + +### 1. waitForMermaid() 函数 +- ✅ 返回 Promise +- ✅ 检查 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} 是否加载成功 + */ +``` + +### ✅ 代码风格 +- 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: 测试各种图表类型