尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

D2 v0.1.4 交互式图表:tooltip 与 link 关键字、附录渲染与布局引擎选项详解

D2 v0.1.4 交互式图表:tooltip 与 link 关键字、附录渲染与布局引擎选项详解 D2 v0.1.4 交互式图表tooltip 与 link 关键字、附录渲染与布局引擎选项详解【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2D2 是一门把文本描述编译成图表的现代图表脚本语言。v0.1.4 是 D2 发展历程中里程碑式的一个版本它首次引入交互式图表能力——图形可以挂载tooltip悬停提示与link点击跳转属性同时把此前仅限图片的width/height关键字开放给所有非容器图形并全面暴露各布局引擎的可配置选项。本文以该版本的官方变更日志ci/release/changelogs/v0.1.4.md为主线结合当前仓库源码逐一拆解这些能力的用法、底层实现与升级注意事项读完即可在自己的 D2 脚本和库调用中直接落地这些新特性。一、交互式图表让静态图形“动”起来v0.1.4 的核心卖点是交互式图表D2 图形现在可以设置tooltip与link。其中tooltip允许读者把鼠标悬停在图形上查看更多信息link允许读者点击图形跳转到外部链接。这一个小改动打开了巨大的想象空间——例如把企业内部 Wiki 通过图表互相串联形成可点击导航的知识图谱。当某个图形带有可悬停的 tooltip 或可点击的链接时D2 会在图形上渲染一个图标作为提示。1.1 关键字在语法层面的定位在 D2 语法树中tooltip与link被定义为一等保留关键字。查看 d2ast/keywords.go 可以看到它们同时出现在两个集合中SimpleReservedKeywordstooltip、link等它们可以直接以key: value的形式附着在图形上CompositeReservedKeywords中的tooltip意味着 tooltip 还可以承载复合对象例如多行文本内容。server: { tooltip: 生产环境主节点承载订单服务 link: https://wiki.example.com/services/order } database: { label: 订单数据库 tooltip: | 只读副本 3 个 主从延迟 500ms link: https://grafana.example.com/d/orders }1.2 从源码看 tooltip/link 的数据结构交互属性最终会被编译进目标图target diagram的 Shape 结构中。在 d2target/d2target.go 中可以看到 Shape 上挂着三个相关字段Tooltip string json:tooltip Link string json:link PrettyLink string json:prettyLink,omitemptyTooltip是悬停时展示的原始文本支持 MarkdownLink是点击跳转的完整 URLPrettyLink是链接的展示文本用于在非交互场景下“尽量美观地”呈现这个链接因为静态导出格式无法点击。而 tooltip 的展示位置由TooltipPosition字段控制d2target/d2target.go。合法取值在 d2ast/keywords.go 的TooltipPositionsArray中定义var TooltipPositionsArray []string{ top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right, }在 SVG 等交互格式中D2 会为带位置的 tooltip 生成一个可见的气泡框在 d2renderers/d2scenebuild/tooltip.go 中buildPositionedTooltip会先按 Markdown 排版 tooltip 内容再根据TooltipPosition计算气泡的坐标调用d2target.CalculateTooltipPosition最后绘制圆角背景框、指向图形的尾巴tail以及 Markdown 文本内容并把这些节点追加到所有图形之后以保证它们始终处于最上层。二、静态导出格式的附录Appendix机制交互特性在 PNG 这类静态导出格式上显然无法工作。因此 v0.1.4 规定当导出到静态格式时tooltip 与 link 会被自动收录进一个“附录”appendix中——每个交互属性对应一个带编号的图标正文下方多出一块编号清单读者虽然无法悬停点击但依然能看到每条元数据。2.1 附录的源码实现附录逻辑集中在 d2renderers/d2scenebuild/appendix.go 中核心流程分三步收集addAppendixItemaddAppendixItem记录每个无法交互呈现的元数据连接线的 tooltip、Markdown 链接标题等并为附录项数量与字符串总字节数设置预算上限受LinkBudget约束测量measureAppendix用文本测量工具计算每一行的宽高逐步累加出附录整体占用的高度并通过expandViewBox在导出时把视口viewBox向下扩展绘制buildAppendix在正文下方先画一条分隔线然后为每一条附录渲染“编号圆形图标 文本”的行。对应地d2renderers/d2svg/appendix/appendix.go 负责在 SVG 序列化阶段把附录真正写进输出文档。2.2 附录图标的位置计算对于正文中的图形D2 会在图形右上角绘制白色圆形编号徽标tooltip 与 link 同时存在时是两个并排徽标。appendixIconCentersappendix.go会根据图形几何类型做特判例如圆形、椭圆、菱形、人形、云、圆柱等图形在同时有两个徽标时会把链接徽标挪到图形内部step、hexagon、queue、page 等形状则把徽标对齐到顶部。例如一个同时带 tooltip 和 link 的矩形导出 PNG 后会形如service: 订单服务 { tooltip: 点击查看监控面板 link: https://grafana.example.com/d/orders }导出 PNG 后图形右上角会出现① ②两个徽标图下方附录区则列出① 订单服务 tooltip: 点击查看监控面板 ② 订单服务 link: https://grafana.example.com/d/orders三、width 与 height不再只是图片的专属在 v0.1.4 之前width和height是 D2 关键字但只对图片icon生效。本次更新把这两个关键字开放给了所有非容器图形box: { width: 200 height: 100 label: 固定尺寸的矩形 } person: 固定尺寸的人形 { width: 120 height: 120 }也就是说任意非容器形状矩形、椭圆、人形、圆柱等现在都可以通过width/height显式控制自身尺寸这让精确排版成为可能。注意容器container即内部还有子图形的形状仍然不适用这两个关键字因为它们的大小由内部内容决定。这一改动与同版本的另一项修复互为表里——图形边框宽度stroke width被纳入图表整体包围盒bounding box的计算详见下文 Bugfix 部分。四、布局引擎选项全面开放v0.1.4 还给了用户“更多控制布局的权力”所有布局引擎的配置项都被暴露出来。D2 在无任何输入的情况下会为每个布局引擎设置合理的默认值因此这些配置属于面向高级用户的特性——需要额外控制时才使用。4.1 dagre 布局引擎的可配置选项dagre 是 D2 默认的布局引擎其配置结构定义在 d2layouts/d2dagrelayout/layout.gotype ConfigurableOpts struct { NodeSep int json:nodesep EdgeSep int json:edgesep } var DefaultOpts ConfigurableOpts{ NodeSep: 60, EdgeSep: 20, }选项默认值含义NodeSep60同一层级内相邻节点之间的间距水平方向EdgeSep20边与边之间的间距水平方向4.2 ELK 布局引擎的可配置选项ELK 布局引擎的配置结构定义在 d2layouts/d2elklayout/layout.gotype ConfigurableOpts struct { Algorithm string json:elk.algorithm,omitempty NodeSpacing int json:spacing.nodeNodeBetweenLayers,omitempty Padding string json:elk.padding,omitempty EdgeNodeSpacing int json:spacing.edgeNodeBetweenLayers,omitempty SelfLoopSpacing int json:elk.spacing.nodeSelfLoop } var DefaultOpts ConfigurableOpts{ Algorithm: layered, NodeSpacing: 70.0, Padding: [top50,left50,bottom50,right50], EdgeNodeSpacing: 40.0, SelfLoopSpacing: 50.0, }选项默认值含义AlgorithmlayeredELK 布局算法默认分层布局NodeSpacing70层内节点间距Padding[top50,left50,bottom50,right50]容器内边距EdgeNodeSpacing40边与节点之间的间距SelfLoopSpacing50自环self-loop边的间距从源码看这些用户选项会与引擎内部固定参数合并newRootLayoutOptionslayout.go在根容器上固定Thoroughness: 8、EdgeEdgeBetweenLayersSpacing: 50、HierarchyHandling: INCLUDE_CHILDREN、CycleBreakingStrategy: GREEDY_MODEL_ORDER等 ELK 原生参数而newContainerLayoutOptionslayout.go在子容器上会关闭 model-order 处理——源码注释明确说明这是为了避免 ELK 0.12 在复合子图上崩溃这也与 v0.1.4 修复的 ELK panic 类问题一脉相承。此外若用户未显式设置SelfLoopSpacing布局器会根据图中自环标签的最大尺寸动态放大该间距防止自环标签互相重叠layout.go。4.3 库调用方式的 Breaking Change把布局选项暴露出来的代价是一个破坏性变更当你把 D2 当作 Go 库使用时d2dagrelayout.Layout与d2elklayout.Layout现在都接受第三个参数options。如果希望保持默认行为请改用各自包下的DefaultLayout// 旧写法v0.1.4 之前 // import github.com/d2lang/d2/d2layouts/d2dagrelayout // err : d2dagrelayout.Layout(ctx, graph) // 新写法v0.1.4 起 import github.com/d2lang/d2/d2layouts/d2dagrelayout // 方式一使用默认选项推荐 err : d2dagrelayout.DefaultLayout(ctx, graph) // 方式二自定义选项 opts : d2dagrelayout.ConfigurableOpts{ NodeSep: 80, EdgeSep: 30, } err : d2dagrelayout.Layout(ctx, graph, opts)ELK 同理import github.com/d2lang/d2/d2layouts/d2elklayout // 默认 err : d2elklayout.DefaultLayout(ctx, graph) // 自定义 opts : d2elklayout.ConfigurableOpts{ Algorithm: layered, NodeSpacing: 90, Padding: [top60,left60,bottom60,right60], EdgeNodeSpacing: 50, SelfLoopSpacing: 60, } err : d2elklayout.Layout(ctx, graph, opts)从实现看DefaultLayout内部就是Layout(ctx, g, nil)——传入 nil 时布局器会回退到包级DefaultOptsd2dagrelayout/layout.go、d2elklayout/layout.go因此两种写法语义完全一致。五、改进与 Bugfix 一览5.1 改进Watch 模式自适应缩放v0.1.4 起watch 模式d2 --watch下渲染内容会自动适配屏幕不再出现图形超出可视区域需要手动滚动/缩放的尴尬。这对使用 watch 模式做交互式编辑的用户是实打实的体验提升。5.2 本次修复的 Bug问题说明class与table空表头渲染错误修复了类图与表格在没有表头时的渲染问题sql_table无列时渲染错误修复了 SQL 表不包含任何列时的渲染问题包围盒未计入描边宽度图表整体 bounding box 现在会为 stroke width 预留空间避免描边被裁切near关键字位置不受控near: top-center这类常量此前在容器上会导致布局错乱或直接报错现在限制near常量只能在合法位置使用并给出友好错误信息而非随机报错。相关合法取值定义在 d2ast/keywords.go 的NearConstantsArray中top-left至bottom-right共 8 个ELK 渲染空标签图片时 panic修复了带空标签的图片走 ELK 布局时程序崩溃的问题需要说明的是由于near关键字值必须是合法的 D2 关键字其常量集合见 d2ast/keywords.go在容器上使用这些常量会破坏容器内子图形的约束因此 v0.1.4 在编译期就拦截这类写法并输出清晰的错误提示。六、升级到 v0.1.4 的注意事项综合以上内容从旧版本升级到 v0.1.4 时需要注意库调用签名变化必须处理如果你的项目直接以 Go 库方式调用d2dagrelayout.Layout或d2elklayout.Layout需要为调用补上第三个参数或直接改用DefaultLayout保持默认行为见 4.3 节示例。near使用受限如果你之前曾在容器上使用near: top-center之类的写法请改为在合法对象上使用否则会得到编译错误这是刻意为之为的是提供确定性行为与友好报错。静态导出会附带附录导出 PNG/GIF/PDF/PPTX 等静态格式时所有 tooltip 与 link 都会自动生成附录行与编号徽标这是预期行为而非缺陷若完全不需要这些元数据就不要在脚本中写tooltip/link。结语v0.1.4 通过tooltip/link把 D2 从“只能看”的静态图表推进到“可以悬停、可以点击”的交互式图表同时借助附录机制保证了静态导出场景下信息不丢失width/height的开放与布局引擎选项的暴露则让高级用户获得了精确排版与深度控制布局的能力。这一版本确立的架构——关键字在 d2ast/keywords.go 中定义、交互数据承载于 d2target/d2target.go 的 Shape 结构、静态附录渲染在 d2renderers/d2scenebuild/appendix.go 与 d2renderers/d2svg/appendix/appendix.go 中实现——至今仍是 D2 交互与静态导出两大能力的基础。如果你正在做企业内部文档体系或需要精确控制版式的图表这个版本引入的能力值得直接上手。【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表