ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Mermaid Swimlanes(泳道图)语法与实战指南:用 subgraph 表达“谁负责“的流程图

Mermaid Swimlanes(泳道图)语法与实战指南:用 subgraph 表达“谁负责“的流程图 Mermaid Swimlanes泳道图语法与实战指南用 subgraph 表达谁负责的流程图【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid导读泳道图Swimlane Diagram是 Mermaid 自v11.16.0起引入的实验性图类型以swimlane-beta为起始关键字语法仍可能在后续版本演进。与普通流程图只回答接下来发生什么不同泳道图通过纵向划分的泳道额外回答这一步归谁负责。本文基于仓库中的官方文档 swimlanes.md渲染后的用户文档见 docs/syntax/swimlanes.md并结合源码完整讲解其声明方式、泳道/节点/连线语法、无障碍声明、专项配置项与布局引擎的实现原理。读完本文你将能直接写出结构清晰的审批流、工单流转与跨团队交付流程并了解该图类型背后复用 flowchart 引擎、仅替换泳道布局的架构设计。什么是泳道图按职责划分的过程图泳道图把一条流程按负责人切开每条泳道lane代表一个参与者actor、团队、系统或阶段泳道内的节点表示发生在该负责人身上的工作箭头表示工作的先后顺序以及发生在泳道之间的交接handoff。当流程中最重要的信息不仅是下一步是什么还包括这一步由谁拥有时就该使用泳道图。典型场景包括审批流申请人 / 审核人 / 系统支持/工单流程客户 → 支持 → 工程交付与履约工作流订单 → 仓储 → 物流任何需要跨团队、跨系统协作的业务过程。快速开始第一个泳道图示例泳道图以swimlane-beta关键字开头随后可用subgraph声明泳道、用 flowchart 风格语法声明节点与连线。下面是一个最基础的客户支持流程swimlane-beta LR subgraph Customer request[Request service] receive[Receive update] end subgraph Support triage[Triage request] answer[Send answer] end subgraph Engineering investigate[Investigate issue] fix[Prepare fix] end request -- triage triage --|Known issue| answer triage --|Needs code change| investigate investigate -- fix -- answer answer -- receive说明本页示例使用了Neo外观与Redux主题渲染开箱即用时泳道图使用你配置的默认 look 与 theme无需额外设置。从渲染结果可以看出请求先在 Customer 泳道发起交接给 Support 泳道做分类遇到需要改代码的分支再交接给 Engineering最终答案又回到 Customer。泳道本身即承担了归属这一维度的信息表达。核心语法声明关键字与方向一个泳道图必须从swimlane-beta关键字开始其后可以可选地跟一个方向声明支持的方向及含义如下方向含义TB从上到下Top to bottomTD自上而下与TB相同BT从下到上Bottom to topLR从左到右Left to rightRL从右到左Right to left若未显式声明方向默认使用TB。从源码角度看swimlane 图对方向的解析完全复用了 flowchart 的语法能力因为它本质上是一个复用 flowchart 解析器、数据库与渲染器仅替换布局引擎的图类型详见下文 实现原理。Lanes泳道用 subgraph 声明泳道使用subgraph ... end块声明。在泳道图中顶层的subgraph会被渲染为泳道。swimlane-beta subgraph Sales lead[Qualify lead] quote[Prepare quote] end为泳道指定内部 id 与显示标签当标签包含空格或希望为样式化提供一个稳定 id 时可以使用subgraph id [label]形式为泳道同时指定内部 id 和展示标签swimlane-beta LR subgraph sales [Sales team] lead[Qualify lead] quote[Prepare quote] end subgraph finance [Finance team] review[Review terms] approve[Approve quote] end lead -- quote -- review -- approveNodes节点flowchart 风格形状泳道内部的节点使用与 flowchart 相同的形状语法先写节点 id再在形状符号内写标签。例如下面覆盖了最常见的几种节点形态起止、普通任务、分支判断swimlane-beta LR subgraph Intake start([Start]) task[Do work] fix[Fix issues] end subgraph Review decision{Ready?} end subgraph Complete done((Done)) end start -- task -- decision decision --|Yes| done decision --|No| fix fix -- task最常见的节点写法与对应形状、用途归纳如下语法形状常见用途id[Text]矩形任务或活动id(Text)圆角矩形步骤或事件id([Text])体育场形两端半圆开始或结束id{Text}菱形决策分支判断问题id((Text))圆形连接点或标记更完整的形状目录图标、图片、Markdown 字符串、类定义与样式化等请直接参见 Flowchart 语法。Edges连线支持同泳道与跨泳道连线同样沿用 flowchart 语法既可以连接同一泳道内的节点也可以跨泳道连接跨泳道连线即交接swimlane-beta LR subgraph Buyer choose[Choose product] pay[Pay invoice] end subgraph Store reserve[Reserve stock] ship[Ship product] end choose -- reserve reserve --|Invoice ready| pay pay -- ship常见的连线写法语法含义A -- B带箭头的连线A --- B无箭头的连线A --\|Label\| B带标签的箭头连线A -.- B虚线箭头A B粗箭头完整的连线语法包括多向箭头、最小连线长度等参见 Flowchart 语法 · Links between nodes。无障碍访问accTitle 与 accDescr与 Mermaid 其他图类型一致泳道图支持使用accTitle与accDescr提供无障碍标题与描述便于屏幕阅读器与辅助技术理解图意swimlane-beta LR accTitle: Support escalation accDescr: A request starts with the customer, is triaged by support, and may be escalated to engineering. subgraph Customer request[Open request] end subgraph Support triage[Triage] end subgraph Engineering resolve[Resolve] end request -- triage -- resolve实现原理基于 flowchart 的 layout-variant 图理解泳道图最好从源码切入。它是一个相当有代表性的架构示例——没有复制 flowchart 的实现而是整体复用了 flowchart 的解析器parser、数据模型db与渲染器renderer只替换了默认布局引擎与泳道专用样式。源码 swimlanesDiagram.ts 中的注释清楚地说明了这一点swimlane 是布局变体图layout-variant diagram它刻意调用 flowchart 的公开工厂函数createFlowDiagram而非重复整个 flowchart 插件这是跨图隔离规则的唯一特许例外——依赖仅作用于 flowchart 的导出入口绝不触碰其内部实现// packages/mermaid/src/diagrams/swimlanes/swimlanesDiagram.ts import { createFlowDiagram } from ../flowchart/flowDiagram.js; import swimlanesStyles from ./styles.js; export const diagram createFlowDiagram({ defaultLayout: swimlane, styles: swimlanesStyles });与之配套的检测与懒加载逻辑位于 detector.ts检测器用正则/^\s*swimlane-beta\b/识别文本是否以swimlane-beta开头然后通过异步 loader 在真正需要渲染时才加载该图插件const detector: DiagramDetector (txt) /^\s*swimlane-beta\b/.test(txt);该插件随后注册进 Mermaid 的图编排表见 diagram-orchestration.ts 中对swimlanes的引入与注册与 flowchart、sequence 等图类型一同参与分发。在样式层面styles.ts 复用 flowchart 的完整样式函数再追加泳道专用规则因为泳道簇cluster形状会自行绘制泳道边界需要把通用的.cluster rect边框抑制掉——具体做法是把其描边颜色与簇背景相匹配并且是主题自适应的而非写死某种颜色const getStyles (options: FlowChartStyleOptions): string ${getFlowchartStyles(options)} .swimlane.cluster rect { stroke: ${options.clusterBorder} !important; } [data-lookneo].cluster rect { filter: none; } ;真正产生泳道布局效果的是defaultLayout: swimlane所指向的专用布局流水线。在 rendering-util/layout-algorithms/swimlanes 目录下可以看到该布局引擎的完整模块负责主干流程的pipeline.ts/layoutCore.ts、方向变换direction/下如lrTransform.ts处理 LR/RL 等方向的坐标换算、泳道内排序__tests__/laneOrdering.spec.ts、正交连线路由器orthogonalRouter/router.ts等同时还有大量针对布局质量的端到端用例如__tests__/pipeline.lr.e2e.spec.ts、15-border-hugging-lr.ddlt.spec.ts。此外 swimlanesDiagram.spec.ts 验证了图类型本身的行为而仓库根目录 e2e/diagrams/swimlanes 下的一组.mmd样例则用于快照级视觉回归。泳道图专项配置SwimlaneDiagramConfig由于复用了 flowchart 渲染器与配置如 curve、htmlLabels、间距等共享选项泳道图的大部分外观由 flowchart 配置控制只有布局管线专用的旋钮集中在SwimlaneDiagramConfig配置块中。其类型定义见 config.type.ts配置项类型含义lineHopsboolean \| arc \| gap把交叉边渲染成小圆弧hops或可见间隙减少重叠边的阅读困难设为false可关闭。渲染为曲线的边会被跳过以免破坏几何形状ignoreCrossLaneEdgesboolean在做泳道分层layer assignment时忽略跨越泳道边界的边。对于含大量跨泳道连线的图可改善层级质量optimizeRanksByCrossingsboolean为泳道布局启用一次感知交叉的等级优化crossing-aware rank optimization扫描automaticLaneOrderingboolean用确定性加权线性排列启发式自动重排顶层泳道。默认关闭——因为源码中泳道的书写顺序本身可能携带语义其中尤其值得注意automaticLaneOrdering源码注释明确说明它默认不启用原因是源码泳道顺序可能承载语义——即在手工编排的泳道图中泳道自左或自上而下的次序常常对应责任方出场顺序。若交给算法重排虽然可能减少交叉却可能改变叙述顺序。配置方式与其他图类型一致可通过initialize或在文本中通过%%{ init: ... }%%指令下发。例如mermaid.initialize({ startOnLoad: true, swimlane: { lineHops: true, automaticLaneOrdering: false, optimizeRanksByCrossings: true, }, });最佳实践让每条泳道只表达一种归属泳道应当回答这一步由谁负责。除非区分团队/阶段/状态正是这张图的表达目的否则不要在同一张图里混用团队、阶段与状态三种维度。swimlane-beta LR subgraph Customer submit[Submit order] confirm[Confirm delivery] end subgraph Store check[Check order] pack[Pack items] end subgraph Carrier collect[Collect package] deliver[Deliver package] end submit -- check -- pack -- collect -- deliver -- confirm为跨泳道交接连线加标签跨泳道箭头意味着责任方的变更。当交接依赖某份文档、一次决策、一条消息或某个条件时请为这条箭头补上标签读者才能知道为什么在这里换人swimlane-beta LR subgraph Applicant apply[Submit application] sign[Sign agreement] end subgraph Reviewer screen[Screen application] decide{Approved?} end subgraph System create[Create account] notify[Send welcome email] end apply --|Application received| screen screen -- decide decide --|Approved| create -- notify -- sign decide --|Needs changes| apply长流程要可一眼读通当泳道或交接数量多到一屏放不下时把一个大的过程拆成多张图。一张好用的泳道图通常应该不需要读者反复追线两遍。swimlane-beta TB subgraph Intake collect[Collect request] validate[Validate details] end subgraph Review review[Review request] decide{Ready?} end subgraph Delivery schedule[Schedule work] complete[Complete work] end collect -- validate -- review -- decide decide --|Yes| schedule -- complete decide --|No| collect使用稳定的 id为节点和泳道使用简短而有意义的 id。标签可以在不破坏连线、样式或后续引用的前提下随意修改因此把引用稳定性寄托在 id 上。注意泳道也支持与 flowchart 相同的类与样式语句swimlane-beta LR subgraph ops [Operations] intake[Receive request] plan[Plan work] end subgraph legal [Legal] review[Review contract] end intake -- plan -- review classDef attention fill:#fff2cc,stroke:#d6a500,color:#111; class review attention;把决策节点放在做决定的人所在泳道决策发生在哪一方就把菱形节点放在哪一方然后让不同分支结果路由到实际执行动作的泳道swimlane-beta LR subgraph Support classify{Can support solve it?} respond[Respond to customer] end subgraph Product prioritize[Prioritize fix] end subgraph Engineering implement[Implement fix] end classify --|Yes| respond classify --|No| prioritize -- implement -- respond何时改用其他图类型泳道图并非万能官方文档给出了清晰的选型边界当归属不重要、只需要表达顺序或分支时改用普通的 flowchart当重点在于参与者之间随时间流动的消息时改用 sequence 顺序图当重点是某一个对象如何随事件改变状态时改用 state 状态图。一句话概括泳道图的价值在于同时呈现流程顺序 责任归属 交接条件三个维度如果你只关心其中一维其他图类型往往更简洁。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表