Mermaid ASCII 渲染器技能#

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

范围与限制#

支持的图表类型#

图表类型支持状态说明Flowchart (流程图)✅ 完全支持graph TD/LR/BT/RL, 子图, 多种节点形状State Diagram (状态图)✅ 完全支持stateDiagram-v2, [*] 起始/结束状态Sequence Diagram (序列图)✅ 完全支持参与者、消息、循环/条件块、注释Class Diagram (类图)✅ 完全支持类定义、属性、方法、继承/组合/关联关系ER Diagram (实体关系图)✅ 完全支持实体、属性、Crow's 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)

输出:

text

┌───┐     ┌───┐     ┌───┐
│   │     │   │     │   │
│ 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 源码结构 (简化版):

text

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