Excalidraw如何嵌入网页？Three.js开发者必看集成方案

Excalidraw 如何嵌入网页？Three.js 开发者必看集成方案

在构建复杂的 3D 可视化应用时，我们常常陷入一个看似微小却影响深远的问题：如何让用户不仅“看到”模型，还能快速理解其背后的逻辑结构？

比如你正在开发一款基于 Three.js 的工业设备数字孪生系统。用户可以旋转、缩放查看每一个零件，但当他们想了解“这个阀门属于哪个子系统？”或“信号流是如何传递的？”时，仅靠三维渲染显然不够。传统的做法是弹出文字说明框，或者跳转到另一份 PDF 文档——体验割裂，信息脱节。

这时候，如果能在页面一侧嵌入一块手绘风格的白板，让系统自动画出结构框图，并允许用户自由添加注释和连线，会是怎样一种体验？这正是Excalidraw能带来的变革。

为什么是 Excalidraw？

Excalidraw 不是一个普通的绘图工具。它以极简的手绘风格、零依赖的组件设计和强大的可编程接口，重新定义了前端中“轻量级图形编辑”的边界。它的核心魅力在于：用最自然的方式表达复杂逻辑。

许多开发者第一次接触 Excalidraw 是通过 Obsidian 或 Notion 插件，但真正让它在技术圈站稳脚跟的，是其作为 npm 包被直接集成进各类工程系统的潜力。尤其是对于 Three.js 开发者来说，在 3D 场景旁嵌入一个可交互的 2D 白板，意味着你可以构建“视觉 + 解释”一体化的信息空间。

想象一下：
- 点击某个机械臂组件 → 自动在右侧白板生成该模块的功能流程图；
- 长按传感器节点 → 弹出手绘式数据流向草图；
- 团队协作评审时，多人同时标注问题区域并拖拽文字说明。

这些场景不再需要跳转外部工具，全部发生在同一个界面内。

技术实现：从零开始嵌入 Excalidraw

安装与基础使用

Excalidraw 提供了官方封装包@excalidraw/excalidraw，支持 React、Vue 甚至原生 JS 项目。安装非常简单：

npm install @excalidraw/excalidraw

然后就可以像普通组件一样使用：

import { Excalidraw } from "@excalidraw/excalidraw"; import { useState } from "react"; function WhiteboardPanel() { const [scene, setScene] = useState({ elements: [], appState: {} }); return ( <div style={{ height: "600px", border: "1px solid #ddd" }}> <Excalidraw initialData={scene} onChange={(elements, appState) => { setScene({ elements, appState }); }} autoFocus /> </div> ); }

就这么几行代码，你就拥有了一个功能完整的虚拟白板。所有绘制内容都会实时以 JSON 形式输出，便于保存或同步。

⚠️ 注意：initialData中的elements必须是只读数组（readonly ExcalidrawElement[]），否则可能引发内部 diff 失效。

深度集成：让 Excalidraw 与 Three.js 协同工作

真正体现价值的地方，是将 Excalidraw 作为“智能注解引擎”，与 Three.js 实现双向联动。

下面是一个典型场景：当你在 Three.js 渲染的 3D 场景中点击某个物体时，系统应自动生成对应的架构示意图，并展现在旁边的白板上。

使用 Imperative API 主动控制画布

Excalidraw 支持通过ref获取命令式 API，允许外部程序主动修改画面内容。这是实现自动化绘图的关键。

import * as THREE from "three"; import { useRef, useEffect } from "react"; import { Excalidraw, ExcalidrawImperativeAPI } from "@excalidraw/excalidraw"; const IntegratedViewer = () => { const excalidrawRef = useRef<ExcalidrawImperativeAPI>(null); const handleObjectSelected = (object: THREE.Object3D) => { const { name, position, scale } = object; // 构建要插入的图形元素 const newElements = [ { type: "rectangle" as const, version: 1, isDeleted: false, id: `node-${Date.now()}`, x: 100, y: 100, width: 180, height: 60, strokeWidth: 2, strokeColor: "#000", backgroundColor: "transparent", fillStyle: "hachure", roughness: 2, opacity: 100, seed: 123456, }, { type: "text" as const, x: 120, y: 120, text: `Component: ${name}\nPosition: (${position.x.toFixed(2)}, ${position.y.toFixed(2)})`, fontSize: 16, fontFamily: 1, textColor: "#000", id: `text-${Date.now()}`, }, ]; // 主动更新白板内容 excalidrawRef.current?.updateScene({ elements: newElements, }); }; useEffect(() => { const scene = new THREE.Scene(); const camera = new THREE.PerspectiveCamera(75, window.innerWidth / 2 / window.innerHeight, 0.1, 1000); const renderer = new THREE.WebGLRenderer(); renderer.setSize(window.innerWidth / 2, window.innerHeight); document.getElementById("three-container")?.appendChild(renderer.domElement); const cube = new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial({ color: 0x00ff00 }) ); cube.name = "Motor_Controller"; scene.add(cube); camera.position.z = 3; // 模拟点击事件 renderer.domElement.addEventListener("click", () => { handleObjectSelected(cube); }); function animate() { requestAnimationFrame(animate); cube.rotation.x += 0.01; cube.rotation.y += 0.01; renderer.render(scene, camera); } animate(); return () => { if (renderer.domElement.parentElement) { renderer.domElement.parentElement.removeChild(renderer.domElement); } }; }, []); return ( <div style={{ display: "flex", height: "100vh" }}> <div id="three-container" style={{ flex: 3 }}></div> <div style={{ width: "1px", background: "#ccc" }}></div> <div style={{ flex: 2, border: "1px solid #ddd" }}> <Excalidraw ref={excalidrawRef} /> </div> </div> ); };

在这个例子中，左侧是 Three.js 渲染的 3D 场景，右侧是 Excalidraw 白板。一旦用户点击立方体，系统立即提取元数据并生成带有标签的矩形框，注入白板。整个过程无需手动绘图，极大提升了信息呈现效率。

关键参数与定制技巧

虽然默认配置已经足够好用，但在实际项目中，你往往需要更精细的控制。以下是几个实用的props使用建议：

此外，还可以通过 CSS 变量覆盖默认样式，例如调整画笔粗细、颜色主题等：

.excalidraw { --color-primary: #005f9e; --stroke-width: 2.5; }

性能与架构设计建议

尽管 Excalidraw 本身性能优异，但在与 Three.js 共存的大规模应用中，仍需注意以下几点：

1. 批量更新优于频繁调用

每次调用updateScene()都会触发重渲染。如果你要一次性插入多个元素（如 AI 自动生成的完整架构图），务必合并成一次调用：

excalidrawRef.current?.updateScene({ elements: [...allNodes, ...allLines, ...allLabels], });

不要逐个添加，否则会导致卡顿。

2. 合理持久化状态

白板内容可通过onChange持续捕获。推荐策略：
- 本地临时缓存：使用localStorage存储当前会话状态；
- 云端同步：结合 WebSocket 或 CRDT 协议实现多端协同；
- 版本管理：将 JSON 导出为快照，支持“回退到上一版”。

3. 移动端适配

Excalidraw 原生支持触控操作，但在小屏幕上建议：
- 增大默认笔刷尺寸；
- 启用手势识别（双指缩放）；
- 隐藏非必要按钮，简化 UI。

4. 权限控制

在企业级应用中，不是所有人都能编辑白板。可通过拦截onChange实现权限判断：

<Excalidraw onChange={(elements) => { if (userHasEditPermission) { saveToServer(elements); } else { alert("您没有编辑权限"); } }} />

更进一步：结合 AI 插件实现智能生成

Excalidraw 社区已有多个 AI 插件尝试，允许用户输入自然语言指令来自动生成图表。例如：

“帮我画一个前后端分离的微服务架构图，包含用户认证、订单服务和消息队列。”

这类功能完全可以集成进你的系统。思路如下：
1. 用户在输入框中描述需求；
2. 调用 LLM API（如 GPT）解析语义，输出结构化节点关系；
3. 将结果转换为 Excalidraw 元素数组；
4. 调用updateScene()注入白板；
5. 用户可在基础上继续编辑优化。

这种方式特别适合快速原型设计、教学演示或需求澄清阶段。

最佳实践总结

经过多个项目的验证，以下是一些值得推广的最佳实践：

• ✅优先使用 NPM 包而非 iframe：获得更高的控制力和更流畅的用户体验；
• ✅统一主题与布局：确保白板与主应用在色彩、字体、间距上协调一致；
• ✅利用 imperative API 实现自动化：把 Excalidraw 当作“可视化输出终端”来使用；
• ✅控制初始加载体积：若非必需，延迟加载 Excalidraw 组件，提升首屏性能；
• ✅提供导出能力：支持一键导出 PNG/SVG，方便分享或嵌入报告。

结语：从可视化到可解释性的跃迁

Excalidraw 的意义，远不止于“加个白板”这么简单。它代表了一种新的设计哲学：让用户不仅能看见，更能理解。

对于 Three.js 开发者而言，掌握这项集成能力，意味着你能构建更具表达力的应用。无论是数字孪生、建筑可视化还是科学模拟，加入 2D 注解层后，信息密度和沟通效率都将得到质的提升。

更重要的是，这种“三维呈现 + 二维解释”的双模态架构，正逐渐成为现代交互式系统的标准范式。而 Excalidraw，以其开源、灵活、美观的特质，无疑是实现这一目标的最佳工具之一。

现在就开始尝试吧——也许下一次的产品评审会上，你的演示就因为那块小小的手绘白板，赢得了全场掌声。