drawio 的 diagramly 应用层架构：分层约束、硬性不变量与关键子系统指南

前端图形学【免费下载链接】drawiodraw.io is a JavaScript, client-side editor for general diagramming.项目地址https://gitcode.com/gh_mirrors/dr/drawio点击查看免费下载导读本文以 diagramly/CLAUDE.md 为核心系统梳理 draw.io 项目中diagramly这一“应用层”的职责边界、关键文件地图、云存储扩展模式以及开发者在改动物件时必须遵守的硬性不变量Hard invariantsMermaid 特性门控、libavoid 路由门控、childLayout 样式编码、布局收敛契约与发布通道机制。读完本文你将掌握 diagramly 与底层 grapheditor/mxgraph 的分层规则知道每种功能对应哪个源码文件、哪篇专项指南以及哪些代码路径“碰都不能碰”。diagramly 是什么draw.io 专用代码层src/main/webapp/js/diagramly/目录承载的是draw.io 特有draw.io-specific的应用层代码它建立在通用图形编辑器grapheditor之上并对其做扩展/覆写。目录内的 CLAUDE.md 开篇就给出了一条铁律般的分层约束grapheditor 和 mxgraph永远不允许反向引用 diagramly。也就是说依赖方向是单向的mxgraph通用图形核心库←grapheditor通用编辑器←diagramlydraw.io 应用层。如果 diagramly 的代码被下沉到 grapheditor/mxgraph 中就会破坏这一单向依赖导致模块间循环引用与架构混乱。关键文件地图CLAUDE.md 列出了一组核心文件每个文件对应一个明确的功能域文件均在src/main/webapp/js/diagramly/下职责App.js主应用继承EditorUi承载应用生命周期、发布通道检查等Editor.js/EditorUi.js对 grapheditor 类的应用级扩展draw.io 侧行为Init.js配置全局量config globalsDrawioFile.js文件抽象层Pages.js多页multi-page支持DiffSync.js协作 diff/patch 同步Menus.js菜单定义含布局容器layoutContainers、flow 顺序等静态配置Settings.jsmxSettings配置Extensions.jsLucidchart / VSDX / Gliffy 导入GraphViewer.js只读查看器Minimal.jssketch 主题Simple.js简单工具栏Trees.js树容器Tree ContainerElkLayout.jsELK 布局的编辑器静态方法绑定LibavoidRouting.jslibavoid 路由的编辑器绑定以实际源码规模佐证当前仓库行数统计EditorUi.js约 33,482 行、Editor.js约 13,955 行、App.js约 9,142 行、Menus.js约 6,224 行、DrawioFile.js约 4,192 行、DiffSync.js约 2,627 行、Pages.js约 2,621 行——可见 EditorUi 是应用层的绝对主体。云存储扩展模式CLAUDE.md 特别点出云存储的实现规律按提供商provider各一组*Client.js/*File.js/*Library.js。当前仓库中完整可见这一模式的实例DriveDriveClient.js、DriveFile.js、DriveLibrary.jsDropboxDropboxClient.js、DropboxFile.js、DropboxLibrary.jsOneDriveOneDriveClient.js、OneDriveFile.js、OneDriveLibrary.jsGitHubGitHubClient.js、GitHubFile.js、GitHubLibrary.jsGitLabGitLabClient.js、GitLabFile.js、GitLabLibrary.jsCLAUDE.md 明确说明 GitLab 扩展自 GitHub即“extends GitHub”TrelloTrelloClient.js、TrelloFile.js、TrelloLibrary.js其中*Client.js负责协议/认证如 DriveClient.js 约 2,729 行*File.js负责文件生命周期保存、加载、同步状态*Library.js负责形状库/素材库的存取。新增一个云存储提供商时照此三件套扩展即可。此外还有两个子目录sidebar/存放 60 个形状面板shape palettes详见 sidebar/CLAUDE.mdvsdx/存放 Visio 编解码器详见 vsdx/CLAUDE.md。专项指南地图先读对应文档再动手CLAUDE.md 用一张映射表指明“在改动某个子系统前先读仓库根目录docs/claude/下的专项指南”。这张表是切入深层原理的门户改动的对象专项指南布局、childLayout 容器、ELK 对话框、布局规格docs/claude/layouts.md正交路由 / libavoidLibavoidRouting.jsdocs/claude/libavoid-routing.mdelk/mermaid/libavoid 原生 bundle 与加载顺序docs/claude/native-bundles.mdMermaid 插入/编辑/图片单元格docs/claude/mermaid.md动画、自定义链接动作AnimationDialogdocs/claude/animations.md校验和错误、DiffSyncdocs/claude/collab-checksum.md导出/打印对话框docs/claude/export-dialogs.md docs/dialog-style-guide.md发布通道checkReleaseChannel、?channel、SW 注册docs/claude/release-channels.md注当前镜像仓库未收录该文件相关实现可查 App.js 中checkReleaseChannel硬性不变量一Mermaid 特性门控必须走EditorUi.isMermaidSupported()CLAUDE.md 规定每一个 Mermaid 入口都必须通过EditorUi.isMermaidSupported()门控禁止裸用isMermaidEnabled或typeof mxMermaidToDrawio检查。源码实现印证了这一规定。在 EditorUi.js 中该帮助函数的定义是EditorUi.isMermaidSupported function() { return window.isMermaidEnabled typeof mxMermaidToDrawio ! undefined typeof mxMermaidToDrawio.parseText function; };三个条件缺一不可window.isMermaidEnabled—— 浏览器必须支持structuredClone原生解析 bundle 的前置要求mxMermaidToDrawio全局存在 —— 原生端口 bundle 已加载mxMermaidToDrawio.parseText是函数 —— 这是最容易被忽略的一点。为什么必须检查parseText而不是只查全局docs/claude/mermaid.md 给出了原因在切换到原生解析器之前构建的extensions.min.js产物中存在一个同名的旧版桥接函数但没有parseText。若只用typeof门控就会在那些旧产物上“宣传”出实际不可用的功能用户一用就失败。这是典型的“门控必须验证能力而非名字”的工程教训。另外parseText的错误契约也很关键返回null严格表示“不支持的图表类型”而一个受支持的图表如果解析/布局/转换失败则抛出MermaidConversionError带真实消息原始错误挂在.cause上绝不会吞掉错误返回 null。这样遥测telemetry才能区分“覆盖缺口”和“解析器 bug”。硬性不变量二libavoid 路由门控走typeof LibavoidRouting ! undefined与 Mermaid 不同libavoid 的门控极其简单路由 UI 的所有入口都只检查typeof LibavoidRouting ! undefined不存在isSupported()/CSP 探测。这背后的原因在 docs/claude/native-bundles.md 中有完整交代js/libavoid-js/libavoid.min.js是 Adaptagrams libavoid C 经 Emscriptenwasm2js编译的纯 JS 产物-sWASM0 -sDYNAMIC_EXECUTION0 -sWASM_ASYNC_COMPILATION0没有 WebAssembly、没有new Function/eval因此既不要求unsafe-eval也不要求wasm-unsafe-eval可在任何 CSP 下运行。它还在加载时同步初始化调用自己的initAvoidModule工厂、设置globalThis.Avoid与window.__libavoidReady。既然没有 CSP 或可用性风险曾经优雅降级的整套机制CSP 探测、__LIBAVOID_UNAVAILABLE、LibavoidRouting.isSupported()就全部删除了。门控对象实质是extensions.min.js是否已加载它携带 libavoid。新增任何 libavoid 入口都必须放在同一个typeof守卫之后。而程序化调用方JSON 布局规格、embed 动作、Run Last Layout 回放在 bundle 初始化失败时仍会暴露翻译后的libavoidUnavailable错误——例如run()会await window.__libavoidReady初始化抛错时它解析为 null。硬性不变量三childLayout JSON 规格必须 URL 编码写入样式布局容器的childLayout样式值在 JSON 形式下必须以 URL 编码URL-encoded形式存在写用Graph.encodeChildLayout读用Graph.decodeChildLayout严禁把原始 JSON 直接拼进keyvalue;样式串。源码印证app.min.js 中的内联实现与 grapheditor/Graph.js 一致Graph.encodeChildLayout function(a) { return encodeURIComponent(JSON.stringify(a)); }; Graph.decodeChildLayout function(a) { return (a ! null (a String(a), a.charAt(0) % (a decodeURIComponent(a)), a.charAt(0) [)) ? JSON.parse(a) : null; };decodeChildLayout体现了兼容性设计若值以%开头先做decodeURIComponent只有解码后以[开头JSON 数组才JSON.parse其他情况如旧版纯字符串flowLayout、treeLayout等返回null走各自旧分支。CLAUDE.md 指出如果不做 URL 编码JSON 中的;、会破坏keyvalue;的样式解析。目前 JSON 写者只有两处Menus.layoutContainers构建器和EditorUi.setContainerChildLayout而唯一读者是initLayoutManager的 getLayoutchildLayout分支通过Graph.decodeChildLayout。decodeChildLayout同时兼容旧版本写入的裸[JSON——存量文件必须保持其 live layout 可用所以旧格式继续被接受。硬性不变量四布局收敛契约——不变的结果必须是“空编辑”这是最容易被忽视、后果也最严重的一条不变量一个收敛converged/unchanged的布局结果必须产生空EMPTY的模型编辑否则布局管理器会无限循环拖垮应用。机理如下布局管理器只在模型发生变化时才重跑childLayout。因此只要 apply 路径上有任何无条件写入就会触发下一次运行、再次写入、再次触发……形成无限循环。docs/claude/layouts.md 记录了真实事故2026-06-21 的生产版本正是这样循环的bundle743419f早于所有防护手写一个 childLayout JSON 样式就把应用冻结在fileChanged自动保存循环里。“空”意味着没有任何写入NO writes而不是净零写入net-zero writes。异步调度器的跨容器终止逻辑依赖这一点嵌套容器会通过管理器的祖先遍历互相重新调度asyncLayoutsApplying只保护正在应用的容器本身所以“先写再还原”write-then-revert的模式就是循环燃料。drawio-elk 侧用一组机制执行该契约值相等几何跳过节点/边收敛后的透明叶子位移通过 0.01守卫无操作、preserveOrigin/透明根锚点以偏移量折进 applier 写入绝不“先裸写再移回”、每个单元格经共享的StyleBatch做一次值守卫的样式写入、_applyEdgeStyle对 applier 路由的边跳过resetEdge。这些守卫同时让协作文本 diff、撤销历史和“已修改”状态保持最小化。硬性不变量五路由调优属于规范核心编辑器绑定只做接线libavoid 的路由/算法调优必须放在规范核心 js/libavoid-js/libavoid-routing.js 中而 diagramly/LibavoidRouting.js只是编辑器绑定模型访问、事件、预览、样式。两者的分工在 docs/claude/libavoid-routing.md 中写得很清楚核心canonical coreglobalThis.AvoidRouting提供computeRoutes与纯几何辅助函数constraintForPoint/jettyStub/filterEnclosing/dirForPoint/clamp01。核心是**模型无关model-free**的只需把Avoid命名空间传入其入口。编辑器绑定adapterLibavoidRouting.computeRoutes只是薄封装把shapeBufferDistance/idealNudgingDistance两个静态量作为选项默认值注入。由于核心与 drawio-mcp命令行工具共享同步规则见 js/libavoid-js/CLAUDE.md。把调优逻辑写进编辑器绑定会破坏“一次调优、两处生效”的同步约定。libavoid 的核心行为概览详见 libavoid 专项指南它不移动任何顶点只把顶点当作障碍物重新路由边支持固定连接点sourceConstraint/targetConstraint{x,y,dir}→ 有向ShapeConnectionPin与每端 jetty 短桩自环边被跳过无终端的悬挂端路由到自由点transparentBounds 组mermaid/PlantUML 包装、布局容器通过getAbsoluteModelBounds解析出派生包围盒作为终点。硬性不变量六发布通道即 SW 注册 URL发布通道release channel机制的根是service worker 注册 URLservice-worker.js对stable/service-worker.js通道状态存于 localStorage 的.drawio-channel只存字面量LITERALS而且SW 缓存键推导逻辑绝不能改变涉及已安装缓存的采纳installed-cache adoption。CLAUDE.md 警告在触碰App.main的注册块、checkReleaseChannel或GenerateServiceWorker之前务必先读 release-channels 专项指南。当前仓库中 App.js 的checkReleaseChannel给出了该机制的关键逻辑App.prototype.checkReleaseChannel function(client) { try { var user (client ! null) ? client.getUser() : null; var email (user ! null) ? user.email : null; var at (email ! null) ? email.lastIndexOf() : -1; // The explicit ?channel override wins for this session. if (at 0 || !isLocalStorage || !Editor.enableServiceWorker || !(serviceWorker in navigator) || urlParams[channel] ! null) { return; } var ts parseInt(localStorage.getItem(.drawio-channel-ts), 10); var elapsed Date.now() - ts; // A future timestamp (corrected clock) must expire, never freeze. if (!isNaN(ts) elapsed 0 elapsed 86400000) ...可以观察到几个设计点?channel查询参数优先只要 URL 带channel参数本会话直接采用该通道跳过后续逻辑前置条件链需要 localStorage、Editor.enableServiceWorker、浏览器navigator.serviceWorker支持时间戳防冻结.drawio-channel-ts记录上次检查时间未来时间戳时钟被校正必须过期而不能冻结——即elapsed 0才可能走缓存路径负值未来时间强制重查缓存窗口为 86400000 ms一天。该机制在App.js中被多处调用如 L1999 的 OneDrive、L2119 的 Drive 等说明不同云存储登录路径都会触发通道检查。结语一份“可交底”的架构契约diagramly/CLAUDE.md的定位不是文档装饰而是一份给所有 diagramly 开发者的可交底契约。它用寥寥数页讲清了四件事分层边界diagramly 只向上依赖 grapheditor/mxgraph反向引用是架构红线文件地图每个功能域对应哪个文件云存储按*Client/*File/*Library三件套扩展专项指南入口改布局、路由、bundle、Mermaid、动画、DiffSync、导出、发布通道前先读docs/claude/下对应指南六条硬性不变量Mermaid 用isMermaidSupported()、libavoid 用typeof守卫、childLayout 用 URL 编码、收敛必须空编辑、路由调优归核心、发布通道即 SW 注册 URL。对于想要为 draw.io 贡献代码的开发者这份契约意味着功能门控的正确姿势、布局系统的收敛纪律、bundle 加载顺序的敏感性都比“写对一行代码”更重要。沿着 CLAUDE.md 给出的地图逐篇深入 layouts.md、libavoid-routing.md、native-bundles.md、mermaid.md即可完整建立从应用层到原生 bundle 的端到端认知。赞分享前端图形学【免费下载链接】drawiodraw.io is a JavaScript, client-side editor for general diagramming.项目地址https://gitcode.com/gh_mirrors/dr/drawio点击查看免费下载相关推荐Claudian Collab 表现层架构Provider 无关契约、跨表面不变量与读写边界Claudian Collab 表现层架构Provider 无关契约、跨表面不变量与读写边界 Claudian 是一个把 Claude Code/CodexAI 应用代码智能体交互助手人工智能AI AgentEverOS 分层架构规范DDD 分层、依赖方向与 import-linter 强制约束实战指南EverOS 分层架构规范DDD 分层、依赖方向与 import linter 强制约束实战指南 EverOS 是一个以 Markdown 为第一存储、面向人工智能AI AgentAgent 记忆RAGgo-admin分层架构深度解析Router→Api→Service→Model四层调用链与红线约束完整指南go admin分层架构深度解析Router→Api→Service→Model四层调用链与红线约束完整指南 go admin 是基于 Gin Vue 的后端认证鉴权上一篇sqlc 插件体系完全指南WASM 与进程插件的配置、原理与实战下一篇【亲测免费】 探秘OpenSpeech一款前沿的开源语音识别与合成框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考