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使用建议：
| 参数 | 说明 | 推荐用法 |
|---|---|---|
theme | 设置亮/暗主题 | 与主应用保持一致，避免视觉割裂 |
viewModeEnabled | 启用只读模式 | 在演示或汇报场景下关闭编辑功能 |
zenModeEnabled | 开启禅模式（隐藏工具栏） | 专注阅读或展示时启用 |
gridSize | 设置背景网格大小 | 建议设为 10 或 20，辅助对齐 |
onChange | 监听变更 | 可用于防抖保存至 localStorage 或后端 |
onPointerUpdate | 鼠标移动回调 | 实现“悬停高亮对应 3D 对象”等联动效果 |
此外，还可以通过 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，以其开源、灵活、美观的特质，无疑是实现这一目标的最佳工具之一。
现在就开始尝试吧——也许下一次的产品评审会上，你的演示就因为那块小小的手绘白板，赢得了全场掌声。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
