nanhaoluo
c37e8da986
- 更新 argon_detect_spam_comment_sync() 使用统一接口 - 更新 argon_extract_keywords_from_comment() 使用统一接口 - 删除旧的 argon_call_ai_api_for_spam_detection() 函数 - 删除旧的 argon_call_ai_for_keyword_extraction() 函数 - 所有 AI 查询现在都通过 argon_ai_query() 统一接口 - 所有查询都会记录到 wp_argon_ai_query_log 数据表 - 支持按场景统计（summary/spam_detection/keyword_extraction）
312 lines
7.9 KiB
Markdown
312 lines
7.9 KiB
Markdown
# 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
|