Excalidraw API接口调用示例：自动化绘图集成方案-程序员充电站

Excalidraw API接口调用示例：自动化绘图集成方案

在现代技术团队的日常协作中，一张清晰的架构图往往胜过千言万语。但现实是，大多数团队仍在手动绘制图表——每次系统变更都要重新调整布局、对齐元素、更新连接线，耗时且容易出错。更糟的是，这些图常常脱离代码存在，很快变得过时。

有没有可能让系统“自己画出自己”？比如提交一段 YAML 配置，CI 流水线自动生成最新的部署拓扑图，并附在发布说明里？或者，在文档中写下“用户通过前端访问订单服务，数据存储在 MySQL”，就能立刻渲染出对应的流程草图？

这正是 Excalidraw 正在帮助我们实现的愿景。它不只是一个手绘风格的白板工具，更是一个可以编程的图形引擎。借助其开放的数据模型和灵活的集成方式，开发者能够将可视化能力嵌入到自动化流程中，真正实现“文档即代码，图表可生成”。

Excalidraw 的核心魅力在于它的极简哲学与强大扩展性的结合。它没有复杂的 UI 层级，所有图形元素都以 JSON 表示，页面状态完全可序列化。这意味着你可以像操作数据一样操作一幅图：读取、修改、批量生成、版本控制、自动校验。这种“状态即文件”的设计，让它天然适合集成进现代工程体系。

虽然官方并未提供 RESTful API 服务，但这反而给了开发者更大的自由度——我们可以基于其公开的excalidraw-element数据结构规范，构建自己的自动化流水线。常见的技术路径包括：

使用 Node.js + Puppeteer/Playwright 在无头浏览器中渲染
利用 React 组件库在前端动态加载场景
结合 CLI 工具进行批量处理
通过 iframe 嵌入第三方系统（如 Notion、Obsidian）

整个自动化流程通常遵循这样一个逻辑链：输入 → 转换 → 渲染 → 输出。输入可能是自然语言描述、YAML 配置或 PlantUML 语法；转换阶段则负责将其解析为符合 Excalidraw schema 的 JSON 数组；接着在渲染环境中还原画面；最终输出 PNG/SVG 图像或.excalidraw文件供后续使用。

// generate-diagram.js const puppeteer = require('puppeteer'); const fs = require('fs'); // 定义图形元素 const elements = [ { type: 'rectangle', x: 100, y: 100, width: 200, height: 80, strokeStyle: 'rough', backgroundColor: '#ffcccb', roughness: 2, label: { text: '前端应用', fontSize: 20 } }, { type: 'ellipse', x: 400, y: 120, width: 120, height: 80, strokeStyle: 'rough', backgroundColor: '#c0e8d5', label: { text: '数据库', fontSize: 20 } }, { type: 'arrow', x: 300, y: 140, points: [[0, 0], [100, 0]], startArrowhead: null, endArrowhead: 'arrow' } ];

上面这段代码定义了一个简单的三层架构雏形：一个矩形代表前端，一个椭圆代表数据库，中间用箭头连接。每个元素都有明确的位置、尺寸、样式和标签属性。关键在于strokeStyle: 'rough'——这是 Excalidraw 实现手绘抖动效果的核心开关，能让生成的图形看起来像是人工草图，降低正式感带来的沟通压力。

接下来，我们需要一个 HTML 容器来承载 Excalidraw 的运行时环境：

<!DOCTYPE html> <html> <head> <title>Auto Diagram</title> <script type="module"> import { restore } from "https://unpkg.com/excalidraw@latest/dist/excalidraw.development.js"; async function init() { const excalidrawContainer = document.getElementById("excalidraw"); const sceneData = { elements: ${JSON.stringify(elements)} }; restore(sceneData, null, null, excalidrawContainer); setTimeout(() => { const canvas = excalidrawContainer.querySelector("canvas"); const dataUrl = canvas.toDataURL("image/png"); document.getElementById("output").value = dataUrl; document.getElementById("form").submit(); }, 1000); } window.onload = init; </script> </head> <body style="margin:0;overflow:hidden;"> <div id="excalidraw" style="width:800px;height:600px;"></div> <form id="form" method="POST" action="http://localhost:3000/receive-image"> <input type="hidden" id="output" name="image"/> </form> </body> </html>

这里的关键是调用restore()方法，它可以将 JSON 数据完整还原为可视化的绘图场景。由于 Excalidraw 是基于 Canvas 渲染的，我们需要等待至少一秒确保所有内容绘制完成，然后通过toDataURL()提取图像的 base64 编码。

主控脚本使用 Puppeteer 加载这个临时页面并捕获输出：

(async () => { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); await page.goto('data:text/html,' + encodeURIComponent(htmlContent), { waitUntil: 'networkidle0' }); page.on('request', req => { if (req.method() === 'POST' && req.url().includes('receive-image')) { const postData = req.postData(); const base64Image = JSON.parse(postData).image.replace(/^data:image\\/png;base64,/, ''); fs.writeFileSync('architecture-diagram.png', base64Image, 'base64'); console.log('✅ 架构图已生成：architecture-diagram.png'); } }); const server = require('http').createServer((req, res) => { let body = ''; req.on('data', chunk => body += chunk); req.on('end', () => { if (req.url === '/receive-image') { res.writeHead(200); res.end('OK'); } }); }).listen(3000); await page.evaluate(() => { document.getElementById("form").submit(); }); setTimeout(() => { server.close(); browser.close(); }, 3000); })();

这套流程虽然简单，但在实际项目中已经足够实用。不过有几个工程细节值得注意：

不要依赖在线 CDN：生产环境建议将excalidraw.development.js打包进本地资源，避免网络波动导致失败。
优先选用 Playwright：相比 Puppeteer，Playwright 支持多浏览器引擎（Chromium/Firefox/WebKit），API 更稳定，性能也更好。
增加重试机制：对于关键任务，应设置超时和最多三次重试策略，提升鲁棒性。
使用浏览器池：高并发场景下频繁启停浏览器代价高昂，可用browser-pool或puppeteer-cluster进行复用。

当然，真正的智能化不止于“程序生成固定图形”。当我们引入 AI 模型后，整个体验会上升一个维度：只需一句话，就能生成复杂的技术图表。

设想这样一个场景：你在写周报时写道：“本周完成了订单微服务拆分，包含 API 网关、认证服务、库存服务和 Redis 缓存。” 如果系统能自动识别这段话中的组件关系，并生成一张带布局的架构图，岂不高效得多？

这就需要借助大语言模型（LLM）来完成语义到结构的映射。以下是一个典型的 Python 脚本示例：

import openai import json openai.api_key = "sk-your-api-key" def generate_excalidraw_json(prompt_desc): system_prompt = """ 你是一个 Excalidraw 图形生成器。根据用户描述，输出符合 excalidraw 元素规范的 JSON 数组。 每个元素必须包含：type, x, y, width, height, label.text, strokeStyle='rough'。 使用大致合理的位置排布元素，箭头连接相关组件。 只返回纯 JSON 数组，不要任何解释。 """ user_prompt = f""" 请生成一个架构图：{prompt_desc} 例如：前端、后端、数据库之间的关系。 """ response = openai.ChatCompletion.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], temperature=0.7, max_tokens=1000 ) raw_output = response.choices[0].message['content'].strip() if raw_output.startswith("```json"): raw_output = raw_output[7:-3] try: elements = json.loads(raw_output) return elements except json.JSONDecodeError as e: print("❌ JSON 解析失败：", raw_output) raise e if __name__ == "__main__": desc = "一个电商系统的架构图，包括用户前端、订单服务、支付服务和MySQL数据库" elements = generate_excalidraw_json(desc) with open("generated_scene.excalidraw.json", "w") as f: json.dump(elements, f, indent=2) print("✅ AI 已生成图形数据到 generated_scene.excalidraw.json")

这个脚本的核心在于精心设计的 system prompt —— 它强制模型输出合法的 JSON 格式，并限定字段范围。实践中发现，如果不加约束，模型很容易输出非标准字段（如color而不是backgroundColor），导致渲染失败。因此，强烈建议配合 JSON Schema 校验库（如jsonschema）做二次验证。

另一个常见问题是坐标混乱。AI 模型本身不具备空间布局能力，容易让多个元素堆叠在一起。解决方案有两种：

预计算布局：先提取组件列表，再用 dagre 等图布局库计算节点位置，最后填充到模板中；
分步提示：使用 LangChain 实现多轮推理，先让模型列出所有组件，再规划连接关系，最后分配坐标区域。

在企业级集成中，典型的自动化架构如下所示：

+------------------+ +---------------------+ | 用户输入 | ----> | AI 解析服务 | | (自然语言/DSL) | | (GPT / LLM Gateway) | +------------------+ +----------+----------+ | v +-----------------------------+ | Excalidraw JSON 生成引擎 | | (添加坐标、样式、连接逻辑) | +--------------+--------------+ | v +------------------------------------+ | Headless Renderer (Puppeteer) | | → 渲染为 PNG/SVG 或返回链接 | +----------------+-------------------+ | v +----------------------+------------------------+ | 文档系统 | CI/CD | 即时通讯 | 知识库 (Obsidian) | +------------------------------------------------+

在这个链条中，Excalidraw 扮演的是“终极渲染器”的角色。上游系统专注于语义理解和结构生成，而视觉呈现交给它完成。例如，在 GitHub Actions 中，每当合并arch.yaml文件时，触发工作流自动调用上述流程，生成最新架构图并上传至制品库。PR 评论区可以直接展示缩略图，评审人员一眼就能看出变更影响。

这种方式解决了几个长期痛点：