feat: 实现 Mermaid 代码块检测函数 - 实现 detectMermaidBlocks 和 isRendered 函数,识别两种格式的 Mermaid 代码块并过滤已渲染的块

This commit is contained in:
2026-01-25 12:54:45 +08:00
parent 96287d87cd
commit 8f7165cede
2 changed files with 191 additions and 185 deletions

View File

@@ -1,188 +1,183 @@
# Mermaid 代码块魔改支持 - 任务列表 # 实施计划:Mermaid 代码块渲染修复
## 概述 ## 概述
实现标准 Markdown 代码块 (` ```mermaid `) 的 Mermaid 图表渲染,通过在代码高亮之前拦截并转换代码块,完全绕过 WordPress 和代码高亮的干扰。
## 任务列表 本实施计划旨在修复 Argon WordPress 主题中 Mermaid 图表渲染的关键问题,并增强交互体验。
### 1. 核心功能实现 **实施策略:**
- 问题优先:优先修复 PJAX 渲染和语法错误问题
- 功能完善:添加导出、全屏查看等功能
- 体验优化:优化交互体验和视觉效果
- 质量保证:确保代码质量和性能
- [ ] 1.1 实现 `convertMermaidCodeblocks()` 函数 ## 任务
- **需求**: 3.1 代码块拦截(核心功能)
- **位置**: `argontheme.js` 第 3942 行之前(`highlightJsRender()` 函数开始处)
- **功能**:
- 使用多个选择器查找 mermaid 代码块
- 支持 `pre > code.language-mermaid``pre > code.mermaid``code.language-mermaid``pre[data-lang="mermaid"]` 格式
- 提取纯文本代码(使用 `textContent`
- 创建 `<div class="mermaid-from-codeblock">` 容器
- 替换原始代码块元素
- 添加 `data-processed="true"` 标记防止重复处理
- **参考**: 设计文档 3.1 节
- [ ] 1.2 集成到 `highlightJsRender()` 函数 ### 阶段 1: 核心问题修复
- **需求**: 3.1 代码块拦截(核心功能)
- **位置**: `argontheme.js` 第 3942 行
- **修改**: 在函数开始处调用 `convertMermaidCodeblocks()`
- **执行顺序**: 转换 → 代码高亮 → Mermaid 渲染
- **参考**: 设计文档 3.2 节(集成点 1
### 2. Mermaid 检测适配 - [ ] 1. 修复 PJAX 页面切换后 Mermaid 不渲染的问题
- [x] 1.1 实现 Mermaid 代码块检测函数 _需求3.1-3.5_
- [~] 1.2 优化 PJAX complete 事件处理 _需求1.1-1.5_
- [~] 1.3 添加渲染状态标记,避免重复渲染 _需求3.5_
- [~] 1.4 测试 PJAX 跳转后的渲染效果 _需求1.1-1.5_
- [ ] 2.1 更新 `detectMermaidBlocks()` 函数 - [ ] 2. 修复 Mermaid 语法解析错误
- **需求**: 3.4 渲染检测 - [~] 2.1 实现 Mermaid 库加载等待机制 _需求2.6, 4.1-4.2_
- **位置**: `argontheme.js` 第 4430 行 - [~] 2.2 优化 Mermaid 初始化配置 _需求2.1-2.4_
- **修改**: 在 selectors 数组中添加 `'div.mermaid-from-codeblock'` - [~] 2.3 添加语法错误处理和友好提示 _需求2.5, 7.1-7.4_
- **优先级**: 放在 `'div.mermaid-shortcode'` 之后,`'div.mermaid'` 之前 - [~] 2.4 测试各种图表类型flowchart、erDiagram、stateDiagram _需求2.2-2.4_
- **参考**: 设计文档 3.2 节(集成点 2
- [ ] 2.2 更新 `extractMermaidCode()` 函数 - [ ] 3. 实现错误处理和降级方案
- **需求**: 3.5 代码提取适配 - [~] 3.1 创建错误提示组件 _需求7.1-7.4_
- **位置**: `argontheme.js` 第 4650 行 - [~] 3.2 实现错误日志记录 _需求14.1-14.6_
- **修改**: 添加对 `mermaid-from-codeblock` 类的处理分支 - [~] 3.3 添加原始代码查看功能 _需求7.2_
- **提取方式**: 使用 `element.textContent` 直接获取 - [~] 3.4 测试各种错误场景 _需求7.1-7.6_
- **参考**: 设计文档 3.2 节(集成点 3
### 3. 测试与验证 ### 阶段 2: 交互功能实现
- [ ] 3.1 创建测试文件 - [ ] 4. 实现工具栏和基础交互
- **需求**: 6.4 测试用例 - [~] 4.1 创建工具栏组件 _需求11.1-11.7_
- **文件**: `tests/test-codeblock-magic.html` - [~] 4.2 实现工具栏自动显示/隐藏 _需求11.1-11.2_
- **内容**: - [~] 4.3 添加按钮提示tooltip _需求11.4_
- 标准 Markdown 代码块 (`pre > code.language-mermaid`) - [~] 4.4 优化工具栏样式(半透明背景) _需求11.3_
- 多个代码块(测试批量处理)
- 特殊字符代码块(`-->`, `--`, `==` 等)
- 空代码块(测试边界情况)
- 多行代码块(测试换行符保留)
- **参考**: 设计文档 7.4 节
- [ ] 3.2 功能测试 - [ ] 5. 实现缩放功能
- **需求**: 6.1 单元测试、6.2 集成测试 - [~] 5.1 实现鼠标滚轮缩放 _需求12.1-12.3_
- **测试项**: - [~] 5.2 实现缩放按钮(放大、缩小、重置) _需求12.4_
- 代码块正确转换为容器 - [~] 5.3 实现双击智能缩放 _需求12.5_
- 代码块不被代码高亮处理 - [~] 5.4 优化缩放动画和性能 _需求12.2-12.3_
- Mermaid 图表正确渲染
- 特殊字符不被转换(`-->` 保持不变)
- 换行符正确保留
- 重复处理防护生效
- **参考**: 设计文档 7.1 节、7.2 节
- [ ] 3.3 PJAX 兼容性测试 - [ ] 6. 实现拖拽功能
- **需求**: 3.6 PJAX 兼容 - [~] 6.1 实现鼠标拖拽移动 _需求12.6-12.8_
- **测试项**: - [~] 6.2 优化拖拽视觉反馈 _需求12.6-12.7_
- 初始页面加载,代码块正确转换和渲染 - [~] 6.3 智能启用/禁用拖拽 _需求12.8_
- PJAX 切换到新页面,新页面的代码块正确转换和渲染 - [~] 6.4 使用 requestAnimationFrame 优化性能 _需求8.1-8.5_
- 已转换的代码块不被重复处理
- 无 JavaScript 错误
- **参考**: 设计文档 3.3 节
- [ ] 3.4 浏览器兼容性测试 ### 阶段 3: 高级功能实现
- **需求**: 6.3 浏览器测试
- **测试浏览器**: Chrome、Firefox、Safari、Edge最新版
- **测试项**: 代码块转换、图表渲染、PJAX 切换、性能表现
- **参考**: 设计文档 7.3 节
### 4. 文档更新 - [ ] 7. 实现图表导出功能
- [~] 7.1 创建导出菜单组件 _需求5.1-5.3_
- [~] 7.2 实现 PNG 导出 _需求5.4_
- [~] 7.3 实现 SVG 导出 _需求5.5_
- [~] 7.4 添加导出错误处理 _需求5.6, 7.5_
- [ ] 4.1 更新用户文档 - [ ] 8. 实现全屏查看功能
- **需求**: 7.1 用户文档 - [~] 8.1 集成 Zoomify 图片查看组件 _需求6.1-6.3_
- **文件**: `docs/mermaid-usage-guide.md` - [~] 8.2 实现全屏按钮和事件处理 _需求6.1-6.2_
- **内容**: - [~] 8.3 支持键盘快捷键ESC 退出) _需求6.4_
- 添加代码块魔改方式的说明 - [~] 8.4 测试全屏模式下的交互功能 _需求6.3-6.5_
- 提供使用示例(标准 Markdown 语法)
- 说明优缺点(优点:标准语法;缺点:需要主题支持)
- 与其他方式的对比
- **参考**: 需求文档 7.1 节
- [ ] 4.2 更新开发者文档 - [ ] 9. 实现主题同步功能
- **需求**: 7.2 开发者文档 - [~] 9.1 监听主题切换事件 _需求9.1-9.3_
- **文件**: `docs/mermaid-developer-guide.md` - [~] 9.2 实现主题自动切换 _需求9.1-9.2_
- **内容**: - [~] 9.3 保持图表状态(缩放、位置) _需求9.4_
- 说明实现原理(提前拦截、转换容器) - [~] 9.4 测试主题切换效果 _需求9.1-9.5_
- 提供代码示例(`convertMermaidCodeblocks()` 函数)
- 说明扩展方式(如何添加新的选择器)
- 执行顺序说明
- **参考**: 需求文档 7.2 节
- [ ] 4.3 更新 FAQ 文档 ### 阶段 4: 性能和体验优化
- **需求**: 7.3 FAQ 文档
- **文件**: `docs/mermaid-faq.md`
- **内容**:
- 添加常见问题(如何使用标准 Markdown 语法?)
- 提供解决方案(启用代码块魔改功能)
- 说明注意事项(需要主题版本 >= X.X.X
- 故障排查指南
- **参考**: 需求文档 7.3 节
### 5. 性能优化(可选) - [ ] 10. 优化渲染性能
- [~] 10.1 实现批量渲染 _需求8.1_
- [~] 10.2 实现延迟加载(优先渲染可见图表) _需求8.2_
- [~] 10.3 添加加载动画 _需求8.3, 11.7_
- [~] 10.4 优化渲染流程,避免阻塞 _需求8.1-8.4_
- [ ] 5.1* 添加性能监控 - [ ] 11. 优化移动端体验
- **需求**: 4.1 性能要求 - [~] 11.1 适配移动端工具栏 _需求10.1_
- **功能**: - [~] 11.2 实现触摸手势支持(双指缩放、单指拖拽) _需求10.2_
- 使用 `performance.now()` 记录转换耗时 - [~] 11.3 优化触摸事件响应 _需求10.5_
- 使用 `console.log()` 输出性能数据(仅调试模式) - [~] 11.4 测试移动端交互体验 _需求10.1-10.5_
- 记录处理的代码块数量
- **目标**: 单个代码块处理时间 < 10ms
- **参考**: 设计文档 5.3 节
- [ ] 5.2* 优化选择器性能 - [ ] 12. 实现生命周期管理
- **需求**: 4.1 性能要求 - [~] 12.1 实现 PJAX 集成(清理和重新渲染) _需求8.5, 16.1-16.5_
- **优化**: - [~] 12.2 实现资源清理函数 _需求16.1-16.5_
- 使用更精确的选择器(减少匹配范围) - [~] 12.3 移除事件监听器,避免内存泄漏 _需求16.2_
- 批量处理元素(减少 DOM 查询次数) - [~] 12.4 测试内存泄漏情况 _需求16.1-16.5_
- 提前返回(跳过已处理的元素)
- **参考**: 设计文档 5.2 节
### 6. 错误处理增强(可选) ### 阶段 5: 代码质量和测试
- [ ] 6.1* 添加错误日志 - [ ] 13. 代码质量检查
- **需求**: 5.3 错误处理 - [~] 13.1 添加 JSDoc 注释 _需求13.2_
- **功能**: - [~] 13.2 遵循项目代码规范Tab 缩进、单引号等) _需求13.1_
- 使用 try-catch 包裹关键代码 - [~] 13.3 使用 let/const 替代 var _需求13.3_
- 捕获异常后记录日志(`console.error()` - [~] 13.4 优化错误处理和日志记录 _需求13.4, 14.1-14.6_
- 不中断其他代码块的处理 - [~] 13.5 代码审查和重构 _需求13.1-13.7_
- **参考**: 设计文档 3.4 节
- [ ] 6.2* 提供降级方案 - [ ] 14. 兼容性测试
- **需求**: 5.3 错误处理 - [~] 14.1 测试主流浏览器Chrome、Firefox、Safari、Edge _需求15.1-15.5_
- **功能**: - [~] 14.2 测试移动端浏览器iOS Safari、Android Chrome _需求15.4_
- 如果转换失败,保留原始代码块 - [~] 14.3 测试降级方案 _需求15.1-15.5_
- 原始代码块仍可通过降级选择器检测(`pre code.language-mermaid` - [~] 14.4 修复兼容性问题 _需求15.1-15.5_
- 确保即使转换失败,仍能渲染
- **参考**: 设计文档 3.4 节
## 任务说明 - [ ] 15. 功能测试
- [~] 15.1 测试 PJAX 页面切换
- [~] 15.2 测试各种图表类型渲染
- [~] 15.3 测试交互功能(缩放、拖拽、全屏)
- [~] 15.4 测试导出功能PNG、SVG
- [~] 15.5 测试错误处理和降级方案
### 优先级 - [ ] 16. 性能测试
- **必须完成**: 1.1 - 2.2核心功能、3.1 - 3.3测试验证、4.1 - 4.3(文档更新 - [~] 16.1 测试渲染性能(多图表页面
- **可选任务**: 5.1 - 5.2性能优化、6.1 - 6.2(错误处理增强) - [~] 16.2 测试内存占用和泄漏
- [~] 16.3 测试交互性能(缩放、拖拽流畅度)
- [~] 16.4 优化性能瓶颈
### 执行顺序 - [ ] 17. 文档和总结
1. 先完成核心功能1.1 - 1.2 - [~] 17.1 更新代码注释
2. 再完成 Mermaid 检测适配2.1 - 2.2 - [~] 17.2 编写使用文档
3. 然后进行测试验证3.1 - 3.4 - [~] 17.3 记录已知问题和限制
4. 最后更新文档4.1 - 4.3 - [~] 17.4 总结优化效果
5. 可选任务可在主要功能完成后进行
### 验收标准 ## 实施优先级
- ✅ 可以使用 ` ```mermaid ` 代码块编写图表
- ✅ 代码块不会被代码高亮处理 **P0 (必须完成 - 核心问题修复):**
- ✅ 图表正确渲染 - 任务 1: 修复 PJAX 渲染问题
- ✅ 特殊字符不被转换 - 任务 2: 修复语法解析错误
- ✅ 换行符正确保留 - 任务 3: 实现错误处理
- ✅ PJAX 切换正常工作
- ✅ 性能无明显影响 **P1 (重要 - 基础交互):**
- ✅ 兼容所有主流浏览器 - 任务 4: 实现工具栏
- 任务 5: 实现缩放功能
- 任务 6: 实现拖拽功能
- 任务 12: 生命周期管理
**P2 (可选 - 高级功能):**
- 任务 7: 图表导出
- 任务 8: 全屏查看
- 任务 9: 主题同步
**P3 (增强 - 优化和测试):**
- 任务 10: 性能优化
- 任务 11: 移动端优化
- 任务 13-17: 质量保证和测试
## 预期效果
### 问题修复
- ✅ PJAX 页面切换后 Mermaid 图表正常渲染
- ✅ 语法解析错误得到修复
- ✅ 错误提示友好,保留原始代码
### 功能增强
- ✅ 支持图表导出PNG、SVG
- ✅ 支持全屏查看(复用图片查看组件)
- ✅ 支持缩放和拖拽
- ✅ 工具栏自动显示/隐藏
### 体验优化
- ✅ 交互流畅,响应迅速
- ✅ 移动端体验良好
- ✅ 主题自动同步
- ✅ 加载动画和视觉反馈
### 代码质量
- ✅ 代码规范,注释完整
- ✅ 错误处理完善
- ✅ 性能优化到位
- ✅ 无内存泄漏
## 注意事项 ## 注意事项
1. **执行顺序约束**: 必须严格遵守"转换 → 代码高亮 → Mermaid 渲染"的执行顺序 1. **向后兼容**:保持现有 API 和配置不变
2. **代码风格**: 使用 Tab 缩进、单引号、严格相等(`===` 2. **性能优先**:避免阻塞主线程,使用批量渲染
3. **安全性**: 使用 `textContent` 而非 `innerHTML`,防止 XSS 3. **错误处理**:所有异步操作都要有错误处理
4. **兼容性**: 保持与现有功能的兼容,不影响 Shortcode 和容器语法 4. **内存管理**:确保事件监听器和 DOM 引用被正确清理
5. **调试**: 添加详细的调试日志,便于追踪问题 5. **测试充分**:测试各种边缘情况和错误场景
## 参考文档
- **需求文档**: `.kiro/specs/mermaid-codeblock-magic/requirements.md`
- **设计文档**: `.kiro/specs/mermaid-codeblock-magic/design.md`
- **代码规范**: `.kiro/steering/code-style.md`

View File

@@ -4879,42 +4879,53 @@ void 0;
/** /**
* 检测所有 Mermaid 代码块 * 检测所有 Mermaid 代码块
* @returns {Array} Mermaid 代码块元素数组 * 需求 3.1-3.5: 扫描页面中的 Mermaid 代码块并过滤已渲染的块
* @returns {HTMLElement[]} 未渲染的 Mermaid 代码块数组
*/ */
detectMermaidBlocks() { detectMermaidBlocks() {
const blocks = []; const blocks = [];
// 检测规则(优先级从高到低) // 需求 3.1: 扫描所有 <pre><code> 元素
const selectors = [ // 需求 3.2: 识别 language-mermaid 类名
'div.mermaid-shortcode', // Shortcode 格式(推荐) document.querySelectorAll('pre code.language-mermaid').forEach(code => {
'div.mermaid-from-codeblock', // 代码块魔改格式(新增) // 需求 3.5: 过滤已渲染的代码块
'div.mermaid', // 标准格式 if (!this.isRendered(code)) {
'pre code.language-mermaid', // Markdown 格式(降级) blocks.push(code);
'pre[data-lang="mermaid"]', // 自定义属性格式 }
'code.mermaid' // 简化格式
];
selectors.forEach(selector => {
const elements = document.querySelectorAll(selector);
elements.forEach(element => {
// 避免重复添加
if (!blocks.includes(element)) {
// 检查是否在注释中
if (!this.isInComment(element)) {
blocks.push(element);
}
}
});
}); });
// 检测 Markdown 容器语法的 Mermaid 代码块 // 需求 3.3: 识别 mermaid 类名
// 格式: ::: mermaid ... ::: document.querySelectorAll('pre code.mermaid').forEach(code => {
this.detectContainerBlocks(blocks); // 需求 3.5: 过滤已渲染的代码块
if (!this.isRendered(code)) {
blocks.push(code);
}
});
this.logDebug(`检测到 ${blocks.length} 个 Mermaid 代码块`); this.logDebug(`检测到 ${blocks.length}未渲染的 Mermaid 代码块`);
return blocks; return blocks;
}, },
/**
* 检查代码块是否已渲染
* 需求 3.5: 避免重复渲染已渲染的代码块
* @param {HTMLElement} element - 代码块元素
* @returns {boolean} 是否已渲染
*/
isRendered(element) {
// 检查元素是否有渲染标记
if (element.hasAttribute('data-mermaid-rendered')) {
return true;
}
// 检查元素是否在 mermaid-container 容器中
if (element.closest('.mermaid-container') !== null) {
return true;
}
return false;
},
/** /**
* 检查元素是否在 HTML 注释中 * 检查元素是否在 HTML 注释中
* @param {HTMLElement} element - 要检查的元素 * @param {HTMLElement} element - 要检查的元素