Mermaid ASCII 渲染器技能

用于在 beautiful-mermaid 项目中理解或使用 ASCII/Unicode 渲染（流程图、状态图、序列图、类图、ER 图）。

范围与限制

支持的图表类型

图表类型	支持状态	说明
Flowchart (流程图)	✅ 完全支持	graph TD/LR/BT/RL, 子图, 多种节点形状
State Diagram (状态图)

✅ 完全支持 | stateDiagram-v2, [*] 起始/结束状态 | | Sequence Diagram (序列图) | ✅ 完全支持 | 参与者、消息、循环/条件块、注释 | | Class Diagram (类图) | ✅ 完全支持 | 类定义、属性、方法、继承/组合/关联关系 | | ER Diagram (实体关系图) | ✅ 完全支持 | 实体、属性、Crows Foot 关系标记 |

不支持的图表类型

• - Gantt (甘特图)
• Pie Chart (饼图)
• Mindmap (思维导图)
• Timeline (时间线)
• User Journey (用户旅程图)
• Git Graph (Git 图表)
• C4Context/C4Container (C4 模型)

版本兼容性

• - 基于版本: beautiful-mermaid v0.1.x
• Node.js: >= 18.0.0
• Bun: >= 1.0.0
• TypeScript: >= 5.0.0

输出限制与边界条件

场景	ASCII 模式	Unicode 模式
长标签 (>20字符)	自动扩展节点宽度，可能影响布局	同左
密集图 (>20节点)

渲染时间增加，建议增大 padding | 同左 | | 复杂路由 | 可能产生锐角，可调整 heuristic | 同左 | | 终端兼容性 | 最佳兼容性，所有终端支持 | 需 UTF-8 支持终端 | | 子图嵌套 | 支持一层子图，多层嵌套可能重叠 | 同左 |

说明：上述阈值为经验建议，实际表现受终端字体、CJK 字符宽度、图表结构影响。问题定位请参考 references/troubleshooting.md。

快速开始

安装

bash
npm install beautiful-mermaid

或

bun add beautiful-mermaid

或

pnpm add beautiful-mermaid

基本使用

typescript
import { renderMermaidAscii } from beautiful-mermaid

const ascii = renderMermaidAscii(graph LR\n A --> B --> C)
console.log(ascii)

输出:

┌───┐ ┌───┐ ┌───┐
│ │ │ │ │ │
│ A │────►│ B │────►│ C │
│ │ │ │ │ │
└───┘ └───┘ └───┘

常见使用方式

不同环境（Node/Bun/浏览器）、同步/异步差异与 SVG/ASCII 选择建议请参考：references/usage.md。

核心 API

renderMermaidAscii

typescript
function renderMermaidAscii(
diagram: string,
options?: AsciiRenderOptions
): string

将 Mermaid 图表渲染为 ASCII/Unicode 字符串（同步执行）。

参数说明：

参数	类型	必填	说明
diagram	string	✅	Mermaid 图表语法字符串
options

AsciiRenderOptions | ❌ | 渲染选项配置 |

AsciiRenderOptions 说明与使用示例请参考：references/usage.md。

SVG/ASCII 选择建议、主题系统说明与多图类型示例分别见：references/usage.md、references/theming.md、references/examples.md。

项目结构参考

beautiful-mermaid 源码结构 (简化版):

src/
ascii/ # ASCII 渲染引擎
index.ts # ASCII 渲染 API 入口
types.ts # 类型定义
canvas.ts # 画布操作
draw.ts # 绘图原语
grid.ts # 网格布局
pathfinder.ts # A* 路径查找
edge-routing.ts # 边路由
sequence.ts # 序列图实现
class-diagram.ts # 类图实现
er-diagram.ts # ER 图实现
converter.ts # 转换器
index.ts # 主 API 入口 (导出 renderMermaid, renderMermaidAscii)
renderer.ts # SVG 渲染
parser.ts # Mermaid 语法解析
layout.ts # 布局引擎
theme.ts # 主题系统

完整细节请参考: references/core-systems.md（低层系统）、references/diagrams.md（图表实现）

何时阅读参考文档

• - 使用方式、API 选项、SVG/ASCII 选择：references/usage.md
• 多图类型最小示例与输出：references/examples.md
• 主题系统与配色策略（SVG）：references/theming.md
• 图表实现细节与布局算法：references/diagrams.md
• 低层渲染系统（类型/画布/绘图/路由）：references/core-systems.md
• Unicode/ASCII 字符表：references/characters.md
• 故障排查与性能建议：references/troubleshooting.md
• 外部链接与资料：references/resources.md