- name
- mermaid-ascii-renderer
- description
- >-
- metadata
- author
- joe
- version
- 1.1.0
- title
- mermaid-ascii-renderer
- description_zh
- >-
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。快速开始
安装
npm install beautiful-mermaid
# 或
bun add beautiful-mermaid
# 或
pnpm add beautiful-mermaid基本使用
import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR\
A --> B --> C`)
console.log(ascii)输出:
┌───┐ ┌───┐ ┌───┐
│ │ │ │ │ │
│ A │────►│ B │────►│ C │
│ │ │ │ │ │
└───┘ └───┘ └───┘常见使用方式
不同环境（Node/Bun/浏览器）、同步/异步差异与 SVG/ASCII 选择建议请参考：references/usage.md。
核心 API
renderMermaidAscii
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