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

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

## 已知问题

### 1. WordPress 编辑器兼容性

#### 问题描述
某些 WordPress Markdown 插件（如 WP-Markdown）会在输出时对 Mermaid 代码进行额外处理，可能导致：
- 代码被包裹在 `<script>` 标签中
- HTML 实体被转义（如 `->` 变成 `&rarr;`）
- 换行符被转换为 `<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