使用 D2 Go 库编程式生成 SVG 与编辑图表：d2lib、d2oracle 与底层 API 实战指南

使用 D2 Go 库编程式生成 SVG 与编辑图表d2lib、d2oracle 与底层 API 实战指南【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2D2 是一款把文本描述转成图表的现代脚本语言turns text to diagrams除了提供命令行工具它还以 Go 库的形式对外暴露了完整的编译、布局、渲染能力。本文以仓库 docs/examples/lib 目录下的三个官方示例为主线讲解如何用 d2lib 把x - y这样的 D2 脚本编译成 SVG、如何借助 d2oracle 编程式地增删改样式并回写 D2 脚本以及如何绕过d2lib直接驱动底层 API 实现同样的流程。读完本文你将掌握在 Go 程序中把 D2 文本渲染为 SVG 的完整调用链并具备在此基础上构建可视化编辑器的能力。一、示例总览三种使用 D2 Go 库的层次docs/examples/lib/README.md 明确给出了 D2 库编程的三种切入层次三个示例相互递进示例目录面向的 API 层次核心能力1-d2libd2lib 高层封装最小化地把x - y编译并渲染为 SVG2-d2oracled2oracle 编辑 API编程式创建形状、设置样式、移动节点并输出格式化后的 D2 脚本3-lowleveld2compiler / d2exporter 等底层 API手动完成编译、布局、导出、渲染的每一步README 特别说明了两点每个示例都可以直接运行go run .但为了可读性刻意省略了错误处理生产代码中必须补上err ! nil检查同时指出d2lib本质上只是底层 API 的薄封装大多数场景直接使用d2lib即可底层 API 通常没必要。二、第一个示例用 d2lib 把x - y渲染成 SVG2.1 完整代码与运行方式1-d2lib/d2lib.go 是官方提供的最小编译示例核心逻辑不足 20 行package main import ( context os path/filepath github.com/d2lang/d2/d2graph github.com/d2lang/d2/d2layouts/d2dagrelayout github.com/d2lang/d2/d2lib github.com/d2lang/d2/d2renderers/d2svg github.com/d2lang/d2/d2themes/d2themescatalog github.com/d2lang/d2/lib/log github.com/d2lang/d2/lib/textmeasure github.com/d2lang/util-go/go2 ) // Remember to add if err ! nil checks in production. func main() { ruler, _ : textmeasure.NewRuler() layoutResolver : func(engine string) (d2graph.LayoutGraph, error) { return d2dagrelayout.DefaultLayout, nil } renderOpts : d2svg.RenderOpts{ Pad: go2.Pointer(int64(5)), ThemeID: d2themescatalog.GrapeSoda.ID, } compileOpts : d2lib.CompileOptions{ LayoutResolver: layoutResolver, Ruler: ruler, } ctx : log.WithDefault(context.Background()) diagram, _, _ : d2lib.Compile(ctx, x - y, compileOpts, renderOpts) out, _ : d2svg.Render(diagram, renderOpts) _ os.WriteFile(filepath.Join(out.svg), out, 0600) }进入 docs/examples/lib/1-d2lib 目录后执行go run .即可生成out.svg。对应的测试 1-d2lib/d2lib_test.go 中的TestMain_直接调用main()go test也可以触发同样的渲染流程。2.2 关键步骤逐项拆解第一步创建文本测量器Ruler。textmeasure.NewRuler()来自 lib/textmeasureD2 需要它来估算文本尺寸从而为节点与标签留出正确的空间。官方注释指出生产环境必须处理这里的错误。第二步注册布局解析器LayoutResolver。d2lib.CompileOptions中的LayoutResolver字段是一个回调函数签名是func(engine string) (d2graph.LayoutGraph, error)见 d2lib/d2.go。示例直接把d2dagrelayout.DefaultLayoutDagre 布局引擎绑定给所有引擎名。从源码 d2lib/d2.go 可以看到D2 还支持通过RouterResolver自定义连线路由未配置时回退到d2layouts.DefaultRouter。第三步构造渲染选项。d2svg.RenderOpts 中示例用了两个字段Pad画布内边距单位为像素示例设为5ThemeID主题 ID示例选用 d2themescatalog 中的GrapeSoda葡萄汽水主题。若这些字段为nild2lib的applyDefaults会自动兜底布局引擎默认dagre主题默认NeutralDefault内边距默认d2svg.DEFAULT_PADDING见 d2lib/d2.go。第四步调用d2lib.Compile。签名返回三元组(*d2target.Diagram, *d2graph.Graph, error)见 d2lib/d2.godiagram可渲染的目标图d2target.Diagram直接交给渲染器graph内部图结构供需要进一步操纵的场景使用第二个示例会用到err错误信息。Compile内部依次完成解析d2parser、编译d2compiler、应用主题与默认配置、设置尺寸、布局d2layouts、导出d2exporter等整条流水线并可递归处理 layers/scenarios/steps 等嵌套板面见 d2lib/d2.go。第五步渲染并写出文件。d2svg.Render(diagram, renderOpts)返回 SVG 字节流用os.WriteFile写入out.svg权限0600。2.3 值得一提的细节外观会影响 Hashd2lib/d2.go 显示Compile会把ThemeID、DarkThemeID、Sketch等外观相关配置回填进diagram.Config其目的是确保用于 CSS 样式的哈希对图的外观唯一。测试 1-d2lib/d2lib_test.go 的TestConfigHash验证了更换主题后HashID会变化TestHashSalt则验证传入不同的 salt如asdf也会产生不同哈希。这说明了哈希同时由外观与盐共同决定对依赖图标识做缓存的场景很重要。三、第二个示例用 d2oracle 编程式编辑图表3.1 为什么需要 d2oracleD2 的设计目标之一是可被hackREADME 明确指出该语言之上构建了一个用于编程式编辑的 API。官方示例 2-d2oracle/d2oracle.go 演示了在第一个示例的基础上用 d2oracle 创建新形状、编程式设置样式、再把修改后的 D2 脚本输出。README 还透露Terrastruct 正是用d2oracleAPI 在可视化界面中把鼠标操作翻译成 D2 编辑动作——这正是该库最典型的应用场景。3.2 完整代码package main import ( context fmt github.com/d2lang/d2/d2format github.com/d2lang/d2/d2graph github.com/d2lang/d2/d2layouts/d2dagrelayout github.com/d2lang/d2/d2lib github.com/d2lang/d2/d2oracle github.com/d2lang/d2/lib/log github.com/d2lang/d2/lib/textmeasure ) // Remember to add if err ! nil checks in production. func main() { // From one.go ruler, _ : textmeasure.NewRuler() layoutResolver : func(engine string) (d2graph.LayoutGraph, error) { return d2dagrelayout.DefaultLayout, nil } compileOpts : d2lib.CompileOptions{ LayoutResolver: layoutResolver, Ruler: ruler, } ctx : log.WithDefault(context.Background()) _, graph, _ : d2lib.Compile(ctx, x - y, compileOpts, nil) // Create a shape with the ID, meow graph, _, _ d2oracle.Create(graph, nil, meow) // Style the shape green color : green graph, _ d2oracle.Set(graph, nil, meow.style.fill, nil, color) // Create a shape with the ID, cat graph, _, _ d2oracle.Create(graph, nil, cat) // Move the shape meow inside the container cat graph, _ d2oracle.Move(graph, nil, meow, cat.meow, false) // Prints formatted D2 script fmt.Print(d2format.Format(graph.AST)) }运行后会在标准输出打印一段格式化好的 D2 脚本创建cat容器创建meow并填充为绿色然后把meow移入cat中。对应测试 2-d2oracle/d2oracle_test.go 同样以TestMain_驱动main()。3.3 d2oracle 核心操作逐一讲解所有编辑操作都遵循传入图、返回新图的纯函数式风格操作底层都是直接修改 D2 的 AST 然后重新编译见 d2oracle/edit.goCreate(g, boardPath, key)新建一个形状或边。第二个参数boardPath用于定位嵌套板面layers/scenarios/steps传nil表示当前主图返回newKey因为自动生成唯一 ID 时可能与请求的 key 不同d2oracle/edit.go。Set(g, boardPath, key, tag, value)设置属性参数含义如下key属性路径示例用meow.style.fill表示把meow的填充色设为绿色值类型是指针tag样式标签如style、label等为nil时从 key 推导value属性值的指针nil表示删除该属性。Move(g, boardPath, srcKey, dstKey, moveToFront)移动节点。示例把meow移到cat.meow即放入cat容器最后一个布尔参数控制是否把移动目标置顶层级顺序。该函数位于 d2oracle/edit.go 中Move相关实现可参考其中的 AST 重组逻辑。Delete(g, boardPath, key)、Rename(g, boardPath, key, newName)、ReconnectEdge与UpdateImport(dsl, path, newPath)也一并暴露在 d2oracle/edit.go分别位于第 937、1699、124、3337 行附近覆盖了图形编辑的增删改查、连线重连与 import 路径更新是构建完整可视化编辑器的地基。3.4 组合 d2format 输出可读脚本d2oracle修改的是内部 AST要把结果还原成 D2 文本需要 d2format.Format示例用fmt.Print(d2format.Format(graph.AST))。d2format会按官方格式规则缩进、引号转义等参见 d2format/escape.go 与 d2format/keypath.go输出整洁的脚本保证编辑后再回写文件的往返体验。3.5 嵌套板面编辑的底层机制当boardPath非空时d2oracle需要先通过GetBoardGraph定位嵌套板面的图对象d2oracle/get.go修改后经ReplaceBoardNode把改好的 AST 片段替换回主 ASTd2oracle/get.go最后重新编译。这解释了为什么编辑操作能精准落在 layers/scenarios/steps 内部而不影响其他板面。四、第三个示例直接驱动底层 API4.1 为什么需要了解底层d2lib.Compile是对底层 API 的封装官方在 README 中直言大多数用例没有必要直接使用底层 API。但当你需要精细控制每个阶段例如自定义测量、按需跳过某一步、与既有管线集成时理解底层调用链就非常关键。3-lowlevel/lowlevel.go 给出了完整的手工流水线package main import ( context os path/filepath strings github.com/d2lang/d2/d2compiler github.com/d2lang/d2/d2exporter github.com/d2lang/d2/d2layouts/d2dagrelayout github.com/d2lang/d2/d2renderers/d2svg github.com/d2lang/d2/d2themes/d2themescatalog github.com/d2lang/d2/lib/log github.com/d2lang/d2/lib/textmeasure ) // Remember to add if err ! nil checks in production. func main() { graph, config, _ : d2compiler.Compile(, strings.NewReader(x - y), nil) graph.ApplyTheme(d2themescatalog.NeutralDefault.ID) ruler, _ : textmeasure.NewRuler() _ graph.SetDimensions(nil, ruler, nil, nil) ctx : log.WithDefault(context.Background()) _ d2dagrelayout.Layout(ctx, graph, nil) diagram, _ : d2exporter.Export(ctx, graph, nil, nil) diagram.Config config out, _ : d2svg.Render(diagram, d2svg.RenderOpts{ ThemeID: d2themescatalog.NeutralDefault.ID, }) _ os.WriteFile(filepath.Join(out.svg), out, 0600) }4.2 与 d2lib 流水线的逐一对照对比 d2lib/d2.go 的实现可以确认d2lib内部做的就是下面这五步只是顺序上d2lib先ApplyTheme再做SetDimensions底层示例先设尺寸后布局两者顺序略有差异但殊途同归编译d2compiler.Compile(inputPath, reader, opts)把 D2 文本解析为*d2graph.Graph与配置d2compiler应用主题graph.ApplyTheme(themeID)示例用NeutralDefault中性默认主题与d2lib的默认值一致设置尺寸graph.SetDimensions(nil, ruler, nil, nil)使用textmeasure.Ruler计算所有文本与形状的尺寸后两个参数对应FontFamily与MonoFontFamily布局d2dagrelayout.Layout(ctx, graph, nil)直接调用 Dagre 布局引擎计算节点坐标导出与渲染d2exporter.Export(ctx, graph, nil, nil)生成d2target.Diagram把config挂回diagram.Config后交给d2svg.Render输出 SVG。这套显式调用链d2compiler → d2layouts/d2dagrelayout → d2exporter → d2renderers/d2svg与d2lib的compileBoard内部实现一一对应可以作为调试自定义管线时的参照物。五、实践要点与进阶方向5.1 生产环境必做的三件事补齐错误处理三个示例都刻意省略了err检查源码注释明确提示 Remember to add if err ! nil checks in production。Compile的三元组返回值、d2oracle各操作的单错误返回都必须逐一检查复用 Ruler 与 LayoutResolvertextmeasure.NewRuler()与布局解析器可以在多次编译间复用避免重复初始化的开销按需配置字体CompileOptions还支持FontFamily/MonoFontFamily见 d2lib/d2.go配合 d2fonts 可控制正文与代码字体Sketch 模式下d2lib会自动切换到手写字体d2lib/d2.go。5.2 三个层次如何选型只需文本 → SVG直接用d2lib.Compiled2svg.Render示例一简单可靠需要编程式编辑、回写脚本在d2lib之上叠加d2oracle示例二适合可视化编辑器、自动化图表生成工具需要定制流水线阶段、深度集成参考示例三直连底层 API但官方建议绝大多数场景不必如此。5.3 更多参考资料官方示例目录docs/examples/lib高层封装实现d2lib/d2.go编辑 APId2oracle/edit.go、d2oracle/get.go配套测试在 d2oracle/edit_test.go 与 d2oracle/get_test.go格式化输出d2format/format.go底层各阶段d2compiler/compile.go、d2layouts/d2dagrelayout/layout.go、d2exporter/export.go、d2renderers/d2svg/d2svg.go主题目录d2themes/d2themescatalog三个示例分别展示了 D2 Go 库的开箱即用可编程编辑与完全掌控三种姿势它们组合起来就是一条从文本到 SVG、再到交互式可视化应用的完整技术路径。【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考