argon-theme/.kiro/specs/mermaid-codeblock-magic/known-issues.md

Mermaid 图表渲染 - 已知问题和限制

已知问题

1. WordPress 编辑器兼容性

问题描述

某些 WordPress Markdown 插件（如 WP-Markdown）会在输出时对 Mermaid 代码进行额外处理，可能导致：

• 代码被包裹在 <script> 标签中
• HTML 实体被转义（如 -> 变成 →）
• 换行符被转换为 <br> 标签

解决方案

渲染引擎已实现以下兼容处理：

• 自动提取 document.write() 中的代码
• 解码 HTML 实体和 Unicode 字符
• 将 <br> 标签转换为换行符

建议

• 推荐使用代码块语法（````mermaid`）
• 避免使用会修改代码的 Markdown 插件
• 如遇问题，可在设置中启用调试模式查看详细日志

2. 复杂图表性能

问题描述

包含大量节点（>50个）的复杂图表可能导致：

• 渲染时间较长
• 页面滚动卡顿
• 移动端性能下降

解决方案

• 已实现批量渲染（每批3个图表）
• 已实现延迟加载（优先渲染可见图表）
• 使用 requestAnimationFrame 优化性能

建议

• 将复杂图表拆分为多个小图表
• 使用子图（subgraph）组织结构
• 避免在一个页面放置过多图表

3. 移动端触摸手势冲突

问题描述

在某些移动浏览器中，触摸手势可能与页面滚动冲突：

• 双指缩放时可能触发页面缩放
• 单指拖拽时可能触发页面滚动

解决方案

• 已使用 preventDefault() 阻止默认行为
• 已使用 passive: false 确保事件可取消

建议

• 在移动端使用全屏模式查看大图表
• 确保浏览器支持触摸事件

4. 主题切换时的闪烁

问题描述

切换主题时，图表重新渲染可能出现短暂闪烁。

解决方案

• 已实现淡入淡出过渡效果
• 已保持图表的缩放级别和位置

影响

• 闪烁时间约 0.5 秒
• 不影响功能使用

5. 导出功能的浏览器兼容性

问题描述

PNG 导出功能依赖 Canvas API，在某些旧版浏览器中可能不支持。

解决方案

• 已添加错误处理和友好提示
• 提供 SVG 导出作为替代方案

建议

• 使用现代浏览器（Chrome 90+, Firefox 88+, Safari 14+）
• 如 PNG 导出失败，使用 SVG 导出

功能限制

1. Mermaid 版本要求

最低版本: Mermaid 9.0+

推荐版本: Mermaid 10.0+

原因:

• 旧版本的 mermaid.render() API 不同
• 某些图表类型在旧版本中不支持

兼容性处理:

• 已实现旧版 API 降级支持（Mermaid 8.x）
• 如果 mermaid.render() 不可用，会尝试使用 mermaidAPI.render()
• 最后降级到 mermaid.init()

2. 图表大小限制

最大节点数: 建议不超过 50 个

最大图表尺寸: 建议不超过 5000x5000 像素

原因:

• 过大的图表会影响渲染性能
• 导出 PNG 时可能超出 Canvas 大小限制

建议:

• 使用子图组织复杂结构
• 将大图表拆分为多个小图表

3. 缩放范围限制

最小缩放: 0.5 倍（50%）

最大缩放: 3 倍（300%）

原因:

• 过小的缩放会导致文字不可读
• 过大的缩放会导致图表超出容器

建议:

• 使用全屏模式查看大图表
• 使用导出功能保存高清图片

4. 全屏模式限制

不支持的浏览器:

• IE 11 及以下版本
• 某些旧版移动浏览器

原因:

• 使用了现代 CSS 特性（如 position: fixed）
• 依赖 JavaScript 事件监听

降级方案:

• 在不支持的浏览器中，全屏按钮会被隐藏
• 用户仍可使用缩放和拖拽功能

5. PJAX 兼容性

要求:

• 必须使用 Argon 主题内置的 PJAX 实现
• 不支持第三方 PJAX 插件

原因:

• 渲染引擎监听 Argon 主题的 PJAX 事件
• 第三方插件的事件名称可能不同

建议:

• 使用主题设置中的 PJAX 选项
• 如使用第三方插件，需手动调用 MermaidRenderer.renderAllCharts()

浏览器兼容性

完全支持

浏览器	最低版本	说明
Chrome	90+	推荐使用
Firefox	88+	推荐使用
Safari	14+	推荐使用
Edge	90+	推荐使用

部分支持

浏览器	版本	限制
Chrome	80-89	某些 CSS 特性不支持
Firefox	78-87	某些 CSS 特性不支持
Safari	13	触摸手势可能不流畅
Edge	80-89	某些 CSS 特性不支持

不支持

浏览器	版本	原因
IE	所有版本	不支持 ES6+ 语法
Chrome	<80	缺少必要的 API
Firefox	<78	缺少必要的 API
Safari	<13	缺少必要的 API

性能基准

渲染性能

图表数量	平均渲染时间	说明
1-5 个	<500ms	流畅
6-10 个	500-1000ms	可接受
11-20 个	1-2s	可能有延迟
>20 个	>2s	建议分页

测试环境: Chrome 120, Intel i5-10400, 16GB RAM

内存占用

图表数量	内存占用	说明
1-5 个	<10MB	正常
6-10 个	10-20MB	正常
11-20 个	20-40MB	可接受
>20 个	>40MB	建议优化

交互性能

操作	响应时间	说明
缩放	<16ms	60fps
拖拽	<16ms	60fps
全屏	<100ms	流畅
导出	500-2000ms	取决于图表大小

安全性说明

1. XSS 防护

措施:

• Mermaid 配置中设置 securityLevel: 'loose'
• 允许 HTML 标签以支持富文本
• 所有用户输入都经过 WordPress 的安全过滤

风险:

• 如果允许未经审核的用户发布文章，可能存在 XSS 风险

建议:

• 只允许可信用户发布包含 Mermaid 图表的文章
• 定期审查文章内容

2. 资源加载

措施:

• Mermaid 库从 CDN 或本地加载
• 不加载外部资源

风险:

• 如果 CDN 被劫持，可能加载恶意代码

建议:

• 使用 HTTPS 加载资源
• 考虑使用本地托管的 Mermaid 库

已修复的问题

v1.0.0 (2026-01-22)

1. ✅ PJAX 页面切换后图表不渲染

   • 原因: 未监听 PJAX complete 事件
   • 解决: 在 PJAX complete 事件中调用 renderAllCharts()

2. ✅ Mermaid 库加载时序问题

   • 原因: 清除缓存后首次加载时 Mermaid 库未完全加载
   • 解决: 实现 waitForMermaid() 等待机制

3. ✅ 语法错误导致页面崩溃

   • 原因: 未捕获 Mermaid 渲染错误
   • 解决: 添加完善的错误处理和友好提示

4. ✅ 重复渲染导致性能问题

   • 原因: 未标记已渲染的图表
   • 解决: 使用 data-mermaid-rendered 属性标记

5. ✅ 主题切换后图表不更新

   • 原因: 未监听主题切换事件
   • 解决: 监听 argon:theme-switched 事件和 darkmode class 变化

6. ✅ 移动端无法缩放和拖拽

   • 原因: 未实现触摸手势支持
   • 解决: 添加双指缩放和单指拖拽支持

7. ✅ 导出功能在某些浏览器中失败

   • 原因: 未处理 Canvas API 错误
   • 解决: 添加错误处理和 SVG 导出替代方案

反馈和建议

如果你遇到了本文档未列出的问题，或有改进建议，请：

1. 检查浏览器控制台: 查看是否有错误信息
2. 启用调试模式: 在控制台执行 window.argonMermaidConfig.debugMode = true
3. 提交 Issue: 在主题 GitHub 仓库提交详细的问题报告
4. 联系作者: 通过主题支持渠道联系

提交 Issue 时请包含:

• 浏览器版本和操作系统
• Mermaid 代码示例
• 错误信息截图
• 控制台日志

更新计划

短期计划（1-3个月）

• 添加更多图表类型支持
• 优化移动端体验
• 添加图表编辑功能
• 支持自定义主题配色

长期计划（3-6个月）

• 添加图表协作功能
• 支持实时预览
• 添加图表模板库
• 支持图表版本控制

---

最后更新: 2026-01-22
文档版本: v1.0.0