D2 v0.1.5 版本特性解析：Crow Foot 关系标记、SVG 自适应屏幕与 Dagre 布局优化

D2 v0.1.5 版本特性解析：Crow Foot 关系标记、SVG 自适应屏幕与 Dagre 布局优化

【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2

本篇技术指南以 D2 项目 v0.1.5 版本的发布说明（ci/release/changelogs/v0.1.5.md）为核心脉络，逐项拆解该版本引入的两大新特性（Crow Foot 箭头标记、SVG 导出自适应屏幕）、一项布局改进（Dagre 边缘间距防标签重叠）以及五个关键 Bug 修复，并结合当前仓库源码（d2target、d2scenebuild、d2svg、d2dagrelayout 等）给出实现层面的佐证。读完本文，你将掌握 v0.1.5 中 Crow Foot 记号的四种取值语义与渲染原理、SVG 自适应屏幕的实现机制，以及这批修复对编译、布局与导出链路的实际影响。

版本背景与更新总览

v0.1.5 是 D2 早期迭代中的一个功能性版本，重点补齐了 ER 图（实体关系图）场景下的关系基数标记能力，同时改善了 SVG 导出的查看体验与 Dagre 布局下的边缘可读性。该版本包含：

• 2 项新特性（Features）：Crow Foot 箭头标记、SVG 导出后自动适配屏幕；
• 1 项改进（Improvements）：Dagre 布局下边缘间距调整，避免标签相互覆盖；
• 5 项缺陷修复（Bugfixes）：覆盖 PNG 导出、watch 模式、编译器维度校验、near标签碰撞与 SQL 表列路由五个方向。

下文按此结构逐一展开，并在每个要点后附上仓库内可交叉验证的源码依据。

新特性一：Crow Foot 关系记号（cf-one / cf-many）

特性含义

Crow Foot（乌鸦脚）是实体关系建模（ERD）中用于表达关系基数（cardinality）的标准记号，常见于 "one"、"many"、"one and only one"、"zero or many" 等语义的表达。v0.1.5 将其引入箭头（arrowhead）体系，使用户在纯文本 D2 脚本中即可描述"一对一""一对多""多对多"等关系约束。

四种取值与语义

在 d2target/d2target.go 中，箭头类型被建模为Arrowhead字符串类型，v0.1.5 新增的四种 Crow Foot 取值如下：

需要说明的是，从渲染实现看，cf-one-required与cf-many-required在"修饰线 + 叉状标记"的组合方式上共享同一套绘制逻辑，区别主要体现在语义命名上；而cf-one使用单条竖线、cf-many使用三线叉状标记，二者的几何生成代码在 d2renderers/d2scenebuild/connection.go 中分别实现。

渲染原理

在 d2renderers/d2scenebuild/connection.go 中，Crow Foot 箭头的绘制分两步完成：

1. 偏移计算：offset := 3 + strokeWidth*1.8，偏移量随线宽动态放大，保证修饰符号与连接线端点之间留有稳定间隙；
2. 修饰符（modifier）生成：
   • 对于-required系列，绘制一条贯穿箭头高度方向的竖直折线（polyline）表示"恰好一个"；
   • 对于非 required 系列，绘制一个空心椭圆（d2scene.Ellipse）作为修饰符；
   • 对于-many系列，额外生成三条从中心向外展开的路径命令（MoveTo/LineTo），构成经典的"乌鸦脚"三叉形状。

当箭头位于连接目标端时，还会通过d2scene.Scale(-1, -1)做镜像变换，使记号方向正确贴合连线方向（connection.go）。

使用示例

在 D2 脚本中，通过source-arrowhead或target-arrowhead关键字指定 Crow Foot 记号。典型 ER 关系描述如下：

customer: { shape: rectangle } order: { shape: rectangle } customer -> order: { source-arrowhead: cf-many target-arrowhead: cf-one-required label: places }

以上脚本表示"一个客户可以下多个订单（many），每笔订单必须属于一个客户（one required）"。所有合法箭头取值（包括 Crow Foot 四种）均在 d2target/d2target.go 的Arrowheads校验表中登记，编译器只接受该集合内的取值。

测试佐证

d2renderers/d2scenebuild/arrowhead_test.go 将四种 Crow Foot 取值列入支持的箭头类型枚举，并覆盖了-required修饰线与-many三叉路径的生成断言，可作为该特性的行为验证入口。

新特性二：导出的 SVG 打开即自动适配屏幕

特性含义

v0.1.5 之前，导出的 SVG 在浏览器或 SVG 查看器中打开时，可能因画布尺寸大于视口而需要手动缩放或滚动。该版本通过为 SVG 根元素补充viewBox与preserveAspectRatio属性，使图形成功适配查看器视口，实现"打开即缩放适配"。

实现机制

在 d2renderers/d2svg/d2svg.go 中，SVG 根标签的生成逻辑如下：

• preserveAspectRatio的两种取值：
  • 默认xMinYMin meet：按左上角对齐、等比缩放并完整容纳整个图形；
  • 当开启居中选项（opts.Center）时为xMidYMid meet：图形在视口内水平垂直居中。
• viewBox：以画布实际宽高（w、h）构造viewBox="0 0 w h"，使外部容器可基于比例自适应缩放。

通过meet语义，图形在任意视口下都能等比完整呈现，且 SVG 仍保留width/height属性作为渲染默认尺寸，不影响后续的精确排版需求（如 PDF/PPTX 转换）。

对动画与 watch 模式的影响

由于动画渲染（opts.MasterID != ""）会改变外层标签结构（不再输出<svg>包装而改用<g>），该版本在实现时明确将自适应包装限制在非动画的常规导出路径上。与此配套的 watch 模式行为见下文 Bugfix 部分——浏览器预览仅在首次加载时执行适配，避免编辑过程中画面被反复缩放。

改进：Dagre 布局下的边缘间距与标签防重叠

v0.1.5 对默认布局引擎（Dagre）的边间距策略做了调整：将 Dagre 边缘彼此拉开，防止标签重叠。

在 d2layouts/d2dagrelayout/layout.go 中，布局参数被建模为ConfigurableOpts，包含两个可配置项：

注释明确说明（对 top-to-bottom 图）：ranksep控制纵向层级间距，nodesep与edgesep控制横向间距。v0.1.5 对边缘间距的调整即作用于EdgeSep维度——当多条边并行连接相邻节点时，更宽的边距能显著降低边缘标签（label）互相遮挡的概率，从而提升复杂依赖图的阅读性。该布局参数最终透传给 Dagre 的edgesep选项（见 layout.go 中rootAttrs的组装逻辑）。

Bugfix 详解：五个修复点的行为与验证

1. PNG 导出不再追加不存在的 Appendix 分隔线

修复前，即使图中没有任何 appendix（附录元素），PNG 栅格化输出仍可能绘制一条多余的分隔线。该版本确保：当附录不存在时，导出中不包含附录分隔线。

佐证：d2cli/raster.go 中注释说明 "Static raster exports paint at most two appendix items (tooltip and ...)"，即栅格导出对附录元素的数量与条件有明确约束，修复使 PNG 输出与该约束保持一致，避免空附录产生视觉残影。

2. Watch 模式仅在初始加载时适配屏幕

配合新特性二，watch 模式（浏览器实时预览）现在只在首次加载时执行"适配屏幕"动作，后续每次文件变更触发的重渲染不再重新缩放视口。这一设计保证用户在编辑过程中保持稳定的缩放与平移状态，避免因反复自适应造成观看跳动。

3. 带 style 的形状上 width/height 不再误报编译错误

此前，对带有样式（style）的形状设置width/height尺寸时，编译器会错误地抛出编译错误。修复后，尺寸属性（width/height）与style的组合使用被正常接受，维度校验逻辑不再与样式块的解析相互干扰。

4. 修复near与边界标签的位置碰撞

near关键字用于将对象吸附到参考点或参考对象附近。此前，当near指向的目标与位于图表边界上同一位置的标签重合时，两者会发生碰撞重叠。该版本修复了位置解析，使near定位与边界标签的排布互不冲突。

5. 修复 SQL 表列路由：列名为表名前缀时的寻路错误

在 SQL 表（sql_table形状）之间连线时，若列名恰好是表名的前缀（例如表名users、列名user），此前路由计算会因名称前缀匹配歧义而选错端口，导致连线起点/终点错误。该版本修正了列端口的路由解析逻辑，确保名称前缀关系不再干扰表间连线的正确寻路。

小结

v0.1.5 以"关系建模体验 + 导出查看体验"为双主线：Crow Foot 记号为 ER 图补齐了标准基数表达（cf-one、cf-many及其-required变体），SVG 自适应屏幕与 watch 初始适配改善了查看与编辑流程；Dagre 边缘间距调整与五项 Bugfix 则分别从布局可读性、导出一致性、编译校验与路由正确性上夯实了基础。对于需要深入验证或二次开发的读者，建议按如下路径继续研读：

• 箭头类型定义与校验表：d2target/d2target.go
• Crow Foot 场景渲染：d2renderers/d2scenebuild/connection.go
• Crow Foot 测试用例：d2renderers/d2scenebuild/arrowhead_test.go
• SVG 自适应屏幕生成：d2renderers/d2svg/d2svg.go
• Dagre 边/节点间距参数：d2layouts/d2dagrelayout/layout.go
• 栅格导出附录约束：d2cli/raster.go

【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2