在 Yank Note 中使用 PlantUML从测试文档到渲染管线的完整指南【免费下载链接】ynA highly extensible Markdown editor featuring version control, AI Copilot, document annotations, mind maps, document encryption, executable code snippets, chart embedding, HTML applets, plugins, and macro replacement. Its integrated sidebar terminal makes working with AI faster and more convenient.项目地址: https://gitcode.com/GitHub_Trending/yn/yn导读本文以 test/md/plantuml.md 测试文档为主线系统讲解 Yank Note 中 PlantUML 图的书写规范、支持的图类型、plantuml-api配置项、本地/在线两种渲染模式及其底层实现。读完你将掌握在 Markdown 文档中编写六类 PlantUML 图的完整语法理解startuml/enduml代码块的解析、压缩与缓存原理并能在本地无 Java 环境下通过在线 API 快速出图。Yank Note 内置了完整的 PlantUML 渲染能力支持顺序图、用例图、类图、活动图、组件图和状态图等多种 UML 图既可在本地借助 Java Graphviz 渲染也可切换到在线 API 服务。test/md/plantuml.md 就是一份覆盖六类典型图的测试样例本文围绕它展开并深入到 渲染插件 与 主进程渲染服务 的源码实现。一、PlantUML 基本语法startuml与enduml标记所有 PlantUML 图都以startuml开头、以enduml结束中间的文本描述图的内容。Yank Note 在 markdown-it 解析器中为这一对标记注册了专门的块级规则uml_diagram并将其转换为img标签由渲染服务生成图片。test/md/plantuml.md中第一个示例是顺序图startuml Alice - Bob: Authentication Request Bob -- Alice: Authentication Response Alice - Bob: Another authentication Request Alice -- Bob: Another authentication Response enduml从源码看markdown-plantuml.ts 将uml_diagram规则注册在 markdown-it 的fence规则之前通过md.block.ruler.before(fence, uml_diagram, uml, ...)实现。这意味着以startuml开头的块会被优先识别为图块而不是普通代码块未闭合的startuml块会在文档末尾自动闭合对应测试 markdown-plantuml.ts 中的 unclosed 用例普通段落文本不会被误判为图块解析器会快速跳过首个字符不匹配的行。除startuml/enduml外插件还注册了 6 组扩展标记markdown-plantuml.tsstartsalt/endsalt界面原型 Salt、startmindmap/endmindmap思维导图、startgantt/endgantt甘特图、startwbs/endwbsWBS 分解、startjson/endjsonJSON 可视化、startyaml/endyamlYAML 可视化。二、六类核心图测试文档逐例拆解1. 顺序图Sequence Diagram顺序图描述对象之间按时间顺序的消息交互-表示同步消息--表示异步返回--表示反向回复startuml Alice - Bob: Authentication Request Bob -- Alice: Authentication Response Alice - Bob: Another authentication Request Alice -- Bob: Another authentication Response enduml该语法可扩展参与者participant、生命线activate/deactivate和分组alt/loop等特性。2. 用例图Use Case Diagram用例图通过actor定义参与者、圆括号(...)定义用例、rectangle定义系统边界。测试文档中的示例恰好描述了 Yank Note 自身的功能startuml left to right direction actor User actor Admin rectangle Yank Note { User -- (Edit Document) User -- (View Preview) User -- (Export PDF) Admin -- (Manage Extensions) Admin -- (Configure Settings) (Edit Document) -- (Save Document) } enduml其中left to right direction指定布局方向为从左到右User -- (Edit Document)表示参与者与用例之间的关联关系。3. 类图Class Diagram类图使用class关键字声明类-表示私有成员、表示公有成员末尾用箭头表达关系与多重性。测试文档定义了一个简化版的文档-编辑器-插件模型startuml class Document { -title: String -content: String -tags: ListString render(): HTML save(): void export(format: String): File } class Editor { -document: Document -plugins: ListPlugin open(path: String): void close(): void } class Plugin { -name: String -version: String activate(): void deactivate(): void } Editor 1 -- 1 Document : edits Editor 1 -- * Plugin : uses enduml末尾两行中的1 -- 1与1 -- *是多重性标注分别表示一个编辑器对应一个文档、一个编辑器使用任意多个插件。4. 活动图Activity Diagram活动图用start/stop定义起止:动作;描述活动if (...) then (分支) ... else (分支) endif描述条件分支。测试文档模拟了文档打开流程startuml start :Open Document; if (Document exists?) then (yes) :Load Content; :Render Preview; else (no) :Create New Document; :Initialize Template; endif :Edit Content; :Save Document; stop enduml5. 组件图Component Diagram组件图用package组织容器、[组件]表示组件、--表示依赖。测试文档描绘了 Yank Note 的模块依赖关系startuml package Yank Note { [Editor] -- [Markdown Engine] [Markdown Engine] -- [Plugins] [Editor] -- [File System] [Plugins] -- [KaTeX] [Plugins] -- [Mermaid] [Plugins] -- [PlantUML] } enduml从仓库源码可以印证这一架构markdown 渲染由 markdown-it 驱动的 markdown.ts 负责KaTeX、Mermaid、PlantUML 等能力均由 plugins.ts 中以插件形式注册其中 PlantUML 即markdownPlantuml。6. 状态图State Diagram状态图用[*]表示初始态与终止态--连接状态转移冒号后标注触发事件startuml [*] -- Draft Draft -- Editing : open Editing -- Saved : save Saved -- Editing : edit Editing -- Preview : toggle Preview -- Editing : toggle Saved -- [*] : close enduml三、两种渲染模式本地 Java 渲染与在线 APItest/md/plantuml.md的 Notes 部分明确了两条要点本地渲染需要 Java 和 Graphviz也可以配置使用在线 API 端点。这两条对应 setting-schema.ts 中plantuml-api配置项的四个取值取值含义前提条件local-png默认本地渲染 PNG本机需安装 Java 与 Graphvizlocal-svg本地渲染 SVG本机需安装 Java 与 Graphvizhttps://www.plantuml.com/plantuml/png/{data}在线渲染 PNG需要网络https://www.plantuml.com/plantuml/svg/{data}在线渲染 SVG需要网络在编辑器设置面板其他分类中修改该配置即可切换模式。本地模式的完整调用链当配置以local开头时主进程渲染服务 plantuml.ts 执行如下流程用commandExists(java)探测 Java 环境缺失时直接返回 no-java-runtime.png 提示图对应测试 plantuml.ts从local-png/local-svg解析出png或svg格式调用plantuml-pipe包启动 plantuml.jar随应用分发在 BIN_DIR并注入-charset UTF-8参数保证中文与 Unicode 字符正确渲染将前端传来的 deflate 压缩数据解压pako.inflateRaw后写入子进程标准输入从标准输出读取渲染结果流。在线模式的请求构造当配置为带{data}占位符的 URL 时plantuml.ts先将图源码做 deflate 压缩 PlantUML 专用 Base64 编码plantumlBase64映射函数见 plantuml.ts将→-、/→_等字符做 URL 安全转换替换 URL 中的{data}占位符得到完整请求地址通过get-proxy-dispatcher动作获取代理调度器走应用配置的代理设置用undici发起请求返回的content-type会覆盖默认推断确保 PNG/SVG 类型准确。对应测试 plantuml.ts 验证了https://plantuml.example/svg/{data}会被转换成带编码数据的请求并通过 dispatcher 发出。四、渲染性能设计磁盘缓存与懒加载基于 SHA-256 的磁盘缓存无论本地还是在线模式渲染结果都会按api type 源码三要素计算 SHA-256 摘要作为缓存键plantuml.ts缓存在用户数据目录的plantuml子目录下命中缓存时直接以流方式返回不再重复渲染或请求测试中连续两次调用只触发一次渲染缓存文件为空size 为 0时视为无效会重新生成缓存数量超过 4000 个时触发 GC按最近访问时间atime排序后清理一半plantuml.ts。编辑器内的懒加载与占位在渲染进程中markdown-plantuml.ts 的Plantuml组件实现了 1 秒防抖debounce加载图片真正进入视图前先显示一个 32×32 的加载占位背景加载完成onLoad后移除背景并恢复自动宽高避免大文档中大量 UML 图同时渲染造成卡顿。五、导出与复制让图出现在 HTML/PDF 中插件注册了VIEW_ON_GET_HTML_FILTER_NODE钩子markdown-plantuml.ts在导出 HTML 时若节点src以/api/plantuml?data开头且导出选项设置了preferPng或inlineLocalImage则会把渲染结果 fetch 回来转成 Base64 data URL 内嵌进 HTML。这样导出的 HTML/PDF 不依赖本地服务可独立打开查看。对应测试 markdown-plantuml.ts 覆盖了内嵌成功与离线失败保持原 src 不变两种情形。六、效率工具自动补全、语法高亮与 Markdown 围栏写法除了startuml标记写法Yank Note 也支持标准 Markdown 围栏fence写法plantuml 代码块 会被 markdown-plantuml.ts 的渲染规则转换为同样的图组件而其他语言的围栏仍走默认代码块渲染。编辑器还内置了成套辅助能力均在 markdown-plantuml.ts 注册自动补全输入/触发补全内置/ PlantUML、/ startuml PlantUML以及 Salt、Mindmap、Gantt、WBS、JSON、YAML 共 8 条模板每条都带可运行的示例源码语法高亮Monarch 词法规则识别startuml/enduml等起始结束标记注意高亮规则中的前缀图块内部内容以变量着色。七、使用前提与注意事项本地模式需要 Java 运行时和 Graphviz生成 PNG 时两者缺一不可SVG 模式对 Graphviz 的依赖相对较小但仍是 PlantUML 官方推荐的环境组合。Java 缺失时编辑器中会显示内置的 no-java-runtime.png 提示图而非报错崩溃。在线模式需要网络连接请求经由应用的代理调度器发出因此应用级代理配置同样生效在线地址中的{data}占位符不可省略否则无法替换为编码后的图源码。图块必须闭合虽然解析器支持文档末尾自动闭合但为避免跨块误吞内容务必成对书写startuml/enduml。测试验证仓库提供了完整的自动化测试来保证上述行为——渲染插件测试见 markdown-plantuml.ts主进程渲染服务测试见 plantuml.ts涵盖标记注册、块解析、围栏渲染、导出内嵌、Java 缺失降级、缓存命中与远程请求等全部关键路径。结语从test/md/plantuml.md中的六类图样例到 markdown-it 块规则、主进程渲染服务、磁盘缓存、导出内嵌与补全/高亮Yank Note 把 PlantUML 从写代码块到看图的完整链路都打通了。你可以直接打开 test/md/plantuml.md 在编辑器预览中逐个验证六类图的效果再按需调整plantuml-api配置选择最适合当前机器的渲染模式。【免费下载链接】ynA highly extensible Markdown editor featuring version control, AI Copilot, document annotations, mind maps, document encryption, executable code snippets, chart embedding, HTML applets, plugins, and macro replacement. Its integrated sidebar terminal makes working with AI faster and more convenient.项目地址: https://gitcode.com/GitHub_Trending/yn/yn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考