Excalidraw状态机图绘制实例教学

Excalidraw状态机图绘制实例教学

在一次产品需求评审会上，团队正讨论订单系统的状态流转逻辑。产品经理在白板上画出“待支付 → 已支付 → 配送中 → 完成”几个方框和箭头，工程师频频点头的同时却在心里叹气：“这图回头还得重画成标准UML，再贴进文档。”这样的场景，在每个技术团队中都再熟悉不过。

有没有一种方式，能让思维的火花直接变成可协作、可复用、甚至能自动演化的技术资产？答案正在浮现——Excalidraw，这款看似“潦草”的手绘风白板工具，正悄然成为现代软件团队的建模利器。它不仅改变了我们画图的方式，更在重塑技术表达与协作的底层逻辑。

想象一下：你只需输入一句“画个文件上传的状态机，包含选择文件、上传中、成功、失败和重试”，下一秒，一张结构清晰、带标签箭头的状态机图就出现在画布上。这不是未来，而是今天通过Excalidraw + AI 镜像就能实现的工作流。它的核心魅力在于，把原本需要专业绘图技能和大量时间的任务，变成了自然语言级别的交互。

Excalidraw 本质上是一个基于 Web 的开源虚拟白板，用 TypeScript 和 React 构建，开箱即用，无需安装。它的界面故意做得像你在纸上随手涂鸦——线条有抖动，字体是手写体，这种“不完美”的美学反而降低了心理门槛，让人更愿意快速表达想法而非纠结于排版对齐。更重要的是，它不只是一个静态画布。每个图形元素背后都是一个结构化的 JSON 对象，这意味着这张“草图”天生就是数据，可以被版本控制、被脚本操作、被 API 调用。

以绘制状态机为例，传统方法是手动拖拽椭圆、输入文字、拉箭头、标注事件。而在 Excalidraw 中，这些都可以自动化。其提供的 Scripting API 允许开发者用代码生成图形。比如下面这段 TypeScript 片段，就能一键创建一个从“初始”到“运行”再到“结束”的三状态机：

// excalidraw-scripting-example.ts import { ExcalidrawElement } from "@excalidraw/excalidraw/types/element/types"; const SCENE_WIDTH = 800; const STATE_RADIUS = 60; const LINE_WIDTH = 2; function createState(x: number, y: number, label: string): ExcalidrawElement { return { type: "ellipse", version: 1, isDeleted: false, id: `state-${label}`, strokeWidth: 2, strokeStyle: "solid", roughness: 2, opacity: 100, x: x - STATE_RADIUS, y: y - STATE_RADIUS, strokeColor: "#000", backgroundColor: "transparent", width: STATE_RADIUS * 2, height: STATE_RADIUS * 2, seed: 1, groupIds: [], boundElements: null, updated: Date.now(), locked: false, }; } function createLabel(x: number, y: number, text: string): ExcalidrawElement { return { type: "text", version: 1, isDeleted: false, id: `label-${text}`, fillStyle: "solid", strokeWidth: 1, strokeStyle: "solid", roughness: 1, opacity: 100, x, y, strokeColor: "#000", backgroundColor: "transparent", width: 80, height: 20, seed: 1, groupIds: [], font: "20px Virgil", text, textAlign: "center", verticalAlign: "middle", containerId: null, originalText: text, locked: false, }; } function createTransition( fromId: string, toId: string, label: string ): ExcalidrawElement { return { type: "arrow", version: 1, isDeleted: false, id: `arrow-${fromId}-${toId}`, strokeWidth: LINE_WIDTH, strokeStyle: "solid", roughness: 2, opacity: 100, x: 0, y: 0, strokeColor: "#000", backgroundColor: "transparent", width: 0, height: 0, seed: 1, groupIds: [], points: [ [0, 0], [50, -30], ], startBinding: { elementId: fromId, focus: 0.5, gap: 10, }, endBinding: { elementId: toId, focus: 0.5, gap: 10, }, endArrowhead: "arrow", label: { text: label, fontSize: 16, fontFamily: 1, textAlign: "left", verticalAlign: "top", x: 0, y: 0, }, locked: false, }; } export function generateStateMachine() { const elements: ExcalidrawElement[] = []; const startX = SCENE_WIDTH / 2; const spacing = 200; const initialState = createState(startX, 100, "initial"); const runningState = createState(startX + spacing, 100, "running"); const finalState = createState(startX + spacing * 2, 100, "final"); const initialLabel = createLabel(startX, 100, "初始"); const runningLabel = createLabel(startX + spacing, 100, "运行"); const finalLabel = createLabel(startX + spacing * 2, 100, "结束"); elements.push(initialState, runningState, finalState); elements.push(initialLabel, runningLabel, finalLabel); const trans1 = createTransition("state-initial", "state-running", "start()"); const trans2 = createTransition("state-running", "state-final", "complete()"); elements.push(trans1, trans2); return elements; }

这个generateStateMachine()函数返回的是一组符合 Excalidraw 数据模型的元素数组。你可以把它封装成插件，点击按钮就生成标准模板，避免每次重复劳动。尤其对于那些有固定模式的系统（如审批流、订单生命周期），这种脚本化生成能节省大量时间。当然，目前 Scripting API 还属于实验性功能，字段细节可能变动，生产环境使用需自行封装兜底逻辑。

但真正的飞跃，来自于AI 镜像的集成。所谓“镜像”，通常指在私有服务器上部署的定制版 Excalidraw，额外挂载了一个 AI 微服务。当你输入一段自然语言描述时，背后的 LLM（如 GPT 系列）会解析语义，识别出状态、事件和转移关系，然后调用类似上面的函数，生成对应的图形指令并注入画布。整个过程就像有个懂技术的助手，把你的想法瞬间可视化。

这个过程的技术链路其实很清晰：

1. 用户输入：“画个用户登录的状态机，包括未登录、登录中、已登录、登录失败”
2. 前端将文本发送至/ai/generate-diagram接口
3. AI 服务调用 LLM，提取结构化信息：
   json { "states": ["未登录", "登录中", "已登录", "登录失败"], "transitions": [ {"from": "未登录", "to": "登录中", "event": "点击登录"}, {"from": "登录中", "to": "已登录", "event": "验证成功"}, {"from": "登录中", "to": "登录失败", "event": "验证失败"} ] }
4. 后端将上述结构映射为 Excalidraw 元素数组，并返回
5. 前端接收后调用scene.replaceAllElements()更新画布

下面是模拟这一过程的 Python 客户端代码：

import requests import json def describe_to_excalidraw_elements(description: str) -> list: """ 将自然语言描述转换为 Excalidraw 元素列表 """ url = "http://localhost:8080/ai/generate-diagram" payload = { "prompt": description, "diagram_type": "state_machine" } headers = { "Content-Type": "application/json" } try: response = requests.post(url, data=json.dumps(payload), headers=headers) if response.status_code == 200: data = response.json() return data.get("elements", []) else: print(f"Error: {response.status_code}, {response.text}") return [] except Exception as e: print(f"Request failed: {e}") return [] # 使用示例 if __name__ == "__main__": desc = "请绘制一个文件上传的状态机，包含：选择文件、上传中、上传成功、上传失败、重试" elements = describe_to_excalidraw_elements(desc) # 输出前5个元素查看结构 for elem in elements[:5]: print(elem["type"], "->", elem.get("label", "") or elem.get("text", ""))

这套架构的精妙之处在于职责分离：Excalidraw 专注渲染与交互，AI 服务专注语义理解，两者通过轻量级接口通信。这不仅保证了主应用的稳定性，也使得 AI 模型可以独立迭代升级。对于企业用户，还可以在 AI 服务中注入领域知识库（如公司内部的术语表），显著提升解析准确率。比如输入“下单”，模型能结合上下文判断这是电商场景而非餐饮，从而生成更贴切的图。

典型的系统架构如下图所示：

graph LR A[Client Browser] --> B[Excalidraw Frontend] B --> C[Backend Server Node] C --> D[Real-time Sync WebSocket/Firebase] C --> E[AI Model Microservice LLM + Parser Engine]

• 前端：承载画布、处理用户输入、执行脚本；
• 后端：管理文件存储、权限控制、多客户端实时同步；
• AI 微服务：作为独立模块，负责自然语言到图结构的转换；
• 数据通道：前端通过 HTTP 请求调用 AI 接口，获取结果后通过本地 API 插入图形。

实际工作流程可能是这样的：一位产品经理在晨会上提出了新的业务流程，他打开公司内部的 Excalidraw 镜像站点，在命令面板输入描述，几秒钟内一张状态机草图就生成了。他随即分享链接，开发、测试、UX 设计师加入协作，大家一边讨论一边在图上标注、修改。会议结束时，这张图已经达成共识，并被导出为 SVG 嵌入需求文档，同时.excalidraw源文件也被提交到 Git 仓库，作为可追溯的技术资产。

相比传统方式，这种工作流解决了多个长期痛点：

• 效率问题：建模从小时级缩短到分钟级，社区反馈普遍认为效率提升 5~10 倍；
• 协作问题：实时光标显示谁在编辑哪部分，评论功能支持异步讨论，彻底告别“我改了你发的那张PNG”的混乱；
• 门槛问题：非技术人员也能参与建模，只要会说话就会画图；
• 资产管理问题：JSON 格式的源文件可 diff、可搜索、可批量处理，真正实现了技术资产的数字化管理。

当然，在落地过程中也有一些关键考量点：

此外，强烈建议结合 Mermaid 插件使用。Mermaid 是一种用代码定义图表的 DSL，Excalidraw 支持双向转换：既可以将 Mermaid 代码渲染成图形，也可以从图形反向生成 Mermaid 代码。这意味着，你的状态机既能以直观的视觉形式呈现，又能以纯文本形式纳入 CI/CD 流程，实现真正的“基础设施即代码”（IaC）理念在设计层面的延伸。

Excalidraw 的意义，早已超越了“画图工具”的范畴。它正在成为技术团队的“数字思维白板”——在这里，想法不再是稍纵即逝的言语或零散的笔记，而是立刻转化为可操作、可协作、可沉淀的结构化资产。从状态机到架构图，从流程图到线框图，每一次绘制都在丰富组织的知识图谱。

更深远的影响在于人机协作范式的转变。过去，我们是工具的使用者；而现在，借助 AI，我们更像是“意图的表达者”。你说出想要什么，系统就帮你构建出来。这种“描述即实现”的能力，正在降低技术创新的认知门槛，让创造力得以更自由地流动。

掌握 Excalidraw，不仅仅是学会一个工具，更是拥抱一种新的工作哲学：快速表达、即时反馈、持续演化。当你的下一个灵感闪现时，别再犹豫——打开 Excalidraw，让它从一句话开始生长。