Figcraft 文档

代码驱动的专业 SVG 图表库，适用于 TypeScript / Node.js。

安装

npm install figcraft

需要 Node.js 18+。该库无浏览器依赖，完全在 Node.js 中运行。

基本用法

创建 diagram.ts 文件，然后用 npx tsx diagram.ts 运行：

import { Figure } from 'figcraft'

const fig = new Figure(800, 400, { bg: '#fff' })

const a = fig.rect('输入', {
  pos: [50, 100], size: [120, 50],
  fill: '#e3f2fd', radius: 6
})

const b = fig.rect('输出', {
  pos: [250, 100], size: [120, 50],
  fill: '#c8e6c9', radius: 6
})

fig.arrow(a, b, { head: 'stealth', label: 'data' })

await fig.export('diagram.svg', { fit: true, margin: 20 })

Figure 构造函数

new Figure(width?: number, height?: number, options?: FigureOptions)

FigureOptions

字体注册

fig.font(name: string, source?: string)

注册字体以在图表中使用：

// 本地系统字体
fig.font('PingFang SC')

// Google Fonts
fig.font('Inter', 'google')

// 自定义 URL
fig.font('MyFont', 'https://example.com/font.woff2')

元素类型概览

Figcraft 提供 10 种元素类型，全部通过 fig.<type>(label, config?) 创建。

2D 图形

矩形 (Rect)

const box = fig.rect('标签', {
  pos: [50, 50], size: [120, 60],
  fill: '#e3f2fd', radius: 8,
  stroke: { color: '#1565c0', width: 2 }
})

圆形 (Circle)

const node = fig.circle('节点', {
  pos: [200, 100], r: 35,
  fill: '#fff3e0', color: '#e65100'
})

菱形 (Diamond)

const decision = fig.diamond('是否?', {
  pos: [100, 100], size: [80, 60],
  fill: '#fce4ec'
})

梯形 (Trapezoid)

const pool = fig.trapezoid('MaxPool', {
  pos: [100, 100], size: [100, 50],
  fill: '#e8f5e9', topRatio: 0.55
})

文本 (Text)

const label = fig.text('**粗体** 和 *斜体*', {
  pos: [100, 50], fontSize: 14
})

图片 (Image)

const img = fig.image('./photo.png', {
  pos: [100, 50], size: [120, 80]
})

3D 图形

圆柱体 (Cylinder)

适合表示数据库和 CNN 特征图。depth 控制椭圆比例（0-1）。

const db = fig.cylinder('数据库', {
  pos: [50, 50], size: [100, 70],
  fill: '#e8f5e9', depth: 0.2
})

长方体 (Cuboid)

3D 方块，适合表示张量和数据体。depth 为挤出距离（像素）。

const tensor = fig.cuboid('特征图', {
  pos: [50, 50], size: [80, 60],
  fill: '#fff8e1', depth: 18
})

球体 (Sphere)

const node = fig.sphere('注意力', {
  pos: [100, 100], r: 35,
  fill: '#e0f7fa'
})

堆叠层 (Stack)

多层堆叠效果。count 设置层数，stackOffset 控制每层偏移量。

const layers = fig.stack('Conv ×4', {
  pos: [50, 50], size: [100, 60],
  fill: '#ede7f6', count: 4,
  stackOffset: [6, -6]
})

ElementConfig

所有属性均为可选，适用于任何元素类型。

嵌套容器

任何元素都可以包含子元素。子元素相对于父元素定位：

const parent = fig.rect('容器', {
  pos: [50, 50], size: [200, 150]
})

// 子元素使用百分比相对定位
parent.circle('中心', { pos: ['50%', '50%'], r: 20 })
parent.rect('左上', { pos: [10, 30], size: [60, 30] })

基本箭头

fig.arrow(source, target, config?)

连接两个元素。未指定锚点时自动吸附到最近边缘。

fig.arrow(a, b)  // 最简形式
fig.arrow(a, b, { head: 'stealth', color: '#1565c0' })

锚点

精确控制箭头连接位置：

// 简单写法：指定边
fig.arrow(a, b, { from: 'right', to: 'left' })

// 详细写法：指定边 + 边上位置（0-100%）
fig.arrow(a, b, {
  from: { side: 'bottom', at: 30 },  // 底边从左起 30% 处
  to: { side: 'top', at: 70 }         // 顶边从左起 70% 处
})

箭头头部类型

内置 11 种箭头头部样式：

路径类型

// 曲线箭头
fig.arrow(a, b, { path: 'curve', curve: 40 })

// 带圆角的折线
fig.arrow(a, b, { path: 'polyline', cornerRadius: 8 })

样式与标签

fig.arrow(a, b, {
  style: 'dashed',           // 'solid' | 'dashed' | 'dotted'
  color: '#e65100',
  width: 2,
  label: '数据流',
  bidirectional: true,       // 双向箭头
  headSize: 10
})

arrows() — 扇出 / 扇入

一次创建多条箭头，支持一对多和多对一：

// 扇出：一个源到多个目标
fig.arrows(source, [targetA, targetB, targetC], {
  head: 'stealth', color: '#1565c0'
})

// 扇入：多个源到一个目标
fig.arrows([srcA, srcB, srcC], target, {
  head: 'triangle', style: 'dashed'
})

fork() — 分支

创建带共享主干的分叉箭头，从一个源分裂到多个目标：

fig.fork(source, [targetA, targetB, targetC], {
  head: 'stealth',
  style: 'solid',
  color: '#333'
})

row()

水平排列元素。第一个元素需要设置 pos。

fig.row([a, b, c], { gap: 40 })  // 默认间距: 40px

col()

垂直排列元素。

fig.col([a, b, c], { gap: 30 })

grid()

网格排列元素。

fig.grid([a, b, c, d, e, f], {
  cols: 3,        // 3 列（默认）
  gap: 20,        // 统一间距
  rowGap: 30,     // 单独设置行间距
  colGap: 15      // 单独设置列间距
})

group()

在元素周围绘制带标签的分组框。需要在布局方法之后调用（需要已确定的位置）。返回一个 Rect，可作为箭头目标使用。

const frame = fig.group([a, b, c], {
  label: '流水线',
  fill: 'rgba(25,118,210,0.05)',
  stroke: { color: '#90caf9', dash: [6, 3] },
  radius: 8,
  padding: 20,
  fontSize: 11,
  fontColor: '#1565c0',
  size: [400, 200]    // 可选固定尺寸（自动居中成员）
})

Markdown 标签格式

所有元素标签支持内联 Markdown 格式：

fig.rect('**Conv2D** $3 \\times 3 \\times 64$', { ... })
fig.text('损失函数: `cross_entropy`', { ... })

导出格式

文件格式根据扩展名自动检测：

// SVG
await fig.export('output.svg', { fit: true, margin: 20 })

// 高分辨率 PNG
await fig.export('output.png', { fit: true, scale: 3, margin: 30 })

// 获取 SVG 字符串（不保存文件）
const svg = fig.render({ fit: true })

ExportOptions

导出格式展示

一份源码，所有格式。点击下方标签对比不同格式的输出效果：

.svg

fig.export('flowchart.svg')

• 矢量格式 — 无限缩放
• 文件体积最小
• 保留完整画布大小

.png

fig.export('flowchart.png')

• 默认 2 倍分辨率
• 白色背景
• 完整画布大小

.jpg

fig.export('flowchart.jpg', {
  fit: true, margin: 20
})

• fit: true 自动裁切
• 内容周围 20px 边距
• 质量: 90（可调）

.png 裁切

fig.export('flowchart-fit.png', {
  fit: true, margin: 20
})

• fit: true 自动裁剪到内容
• 去除多余空白区域
• 嵌入文档时效果最佳

.png 透明

// 不设 bg = 透明背景
const fig = new Figure(800, 350)
fig.export('out.png', { fit: true })

• 省略 bg 即为透明
• 棋盘格 = Alpha 通道
• 叠加使用效果极佳

.webp

fig.export('flowchart.webp', {
  fit: true, margin: 20
})

• 现代格式，体积更小
• 支持透明度
• 适合网页发布

MCP 集成

Figcraft 内置 MCP（Model Context Protocol）服务端。Claude Code、Cursor 等 AI 智能体可以无需编写代码，直接生成图表。

配置

添加到 Claude Code 或 Cursor 的 MCP 设置中：

{
  "mcpServers": {
    "figcraft": {
      "command": "npx",
      "args": ["figcraft-mcp"]
    }
  }
}

然后用自然语言描述你的图表即可："画一个 Transformer 架构图，包含编码器和解码器堆叠"。

MCP 工具

JSON 规范格式

create_diagram 工具接受以下 JSON 结构：

{
  "width": 800,
  "height": 400,
  "bg": "#ffffff",
  "fontFamily": "Arial",
  "autoAlign": true,
  "elements": [
    {
      "id": "a",
      "type": "rect",
      "label": "输入",
      "pos": [50, 100],
      "size": [120, 60],
      "fill": "#e3f2fd",
      "radius": 6
    },
    {
      "id": "b",
      "type": "rect",
      "label": "输出",
      "pos": [300, 100],
      "size": [120, 60],
      "fill": "#c8e6c9"
    }
  ],
  "arrows": [
    {
      "from": "a",
      "to": "b",
      "fromSide": "right",
      "toSide": "left",
      "label": "data",
      "head": "stealth"
    }
  ],
  "groups": [
    {
      "members": ["a", "b"],
      "label": "流水线",
      "padding": 20,
      "stroke": "#999"
    }
  ],
  "layouts": [
    { "type": "row", "elements": ["a", "b"], "gap": 40 }
  ],
  "fanArrows": [
    { "from": "src", "to": ["a", "b", "c"] }
  ],
  "forks": [
    { "from": "root", "to": ["x", "y", "z"] }
  ],
  "export": {
    "path": "output.svg",
    "fit": true,
    "margin": 20
  }
}

Figure 类 — 所有方法

ElementConfig — 完整参考

ArrowConfig — 完整参考

ExportOptions — 完整参考