Mermaid 泳道图Swimlanes Diagram语法详解从 swimlane-beta 语法到源码级实现原理【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 仓库中的官方语法文档 docs/syntax/swimlanes.md 展开系统讲解泳道图Swimlanes Diagram的完整语法——方向声明、泳道定义、节点形状、连线语法与无障碍标注并结合 swimlanesDiagram.ts 等源码解释布局变体图如何复用 flowchart 解析器与渲染器、泳道布局引擎Sugiyama 管线的工作方式以及默认泳道、主题变量、样式语句在实现中的实际行为。读完本文你可以直接编写生产可用的swimlane-beta图并理解其底层的布局与渲染机制。需要说明的适用前提泳道图是 Mermaid 的新图表类型自v11.16.0引入官方文档明确提示其语法可能在后续版本中演进使用时以当前仓库文档为准。什么是泳道图适合什么场景泳道图将流程按职责切分每条泳道lane代表一个角色、团队、系统或阶段泳道内的节点表示该职责范围内发生的工作箭头表示工作顺序以及跨泳道的交接handoff。官方文档给出的核心判断标准是当你关心的不只是下一步发生什么还有谁负责这一步时就适合用泳道图。典型应用包括审批流程、支持工单处理、交付工作流以及任何工作会跨越团队或系统的流程。与相邻图型的边界引自原文档 When to Use Another Diagram 一节所有权不重要、只需展示顺序或分支 → 用普通 flowchart关注点是在时间轴上参与者之间的消息 → 用 sequenceDiagram关注点是单个事物如何改变状态 → 用 stateDiagram。基本示例官方文档中的第一个完整示例是一个客户 / 客服 / 工程三方支持流程。注意文档提示在线示例渲染使用 Neo 外观与 Redux 主题而开箱即用out of the box的泳道图遵循你配置的默认 look 和 theme这条流程里有两处跨泳道交接客服分诊后按已知问题/需要改代码分叉工程侧修复完成后回到客服的answer节点最终回流到客户的receive节点——这正是泳道图相比普通流程图多表达出来的责任变化点。语法swimlane-beta关键词与方向声明泳道图以swimlane-beta关键词开头其后可选跟一个方向swimlane-betaswimlane-beta LR支持的方向及其含义完整继承自原文档的方向表DirectionMeaningTBTop to bottomTDTop down, same asTBBTBottom to topLRLeft to rightRLRight to left不写方向时默认使用TB。源码印证一解析器层面。在 flow.jison 中swimlane-beta被注册为与graph/flowchart同级的图类型关键词swimlane-beta {if(yy.lex.firstGraph()){this.begin(dir);} return GRAPH;}也就是说swimlane-beta走的正是 flowchart 的词法入口firstGraphdir状态这从机制上解释了为什么它的方向词、节点形状、连线、classDef、style、linkStyle都能直接复用 flowchart 语法。测试 flow.spec.js 也断言了swimlane-beta LR;A--B;可以被解析。源码印证二图类型检测。插件定义在 detector.ts 中检测规则是对文本做正则匹配const detector: DiagramDetector (txt) { return /^\s*swimlane-beta\b/.test(txt); };即文本必须以swimlane-beta开头前导空白允许命中后异步加载swimlanesDiagram.ts。这也意味着swimlane-beta必须出现在文档首行。源码印证三默认方向。e2e 测试 swimlanes.spec.ts 中名为defaults to the swimlanes layout without an explicit layout config的用例验证了不写layout配置时图自动使用泳道布局且每条顶层subgraph都渲染为g.cluster.swimlane元素测试断言了 2 条泳道对应 2 个 cluster。泳道Lanes顶层 subgraph 即泳道在泳道图中顶层 subgraph 被渲染为泳道泳道以end结束。最小示例泳道可以带内部 id 和显示标签这在标签含空格、或需要稳定 id 用于后续样式引用时很有用默认泳道行为源码补充原文档未覆盖。swimlanes.spec.ts 中的puts nodes without an explicit subgraph into a default swimlane用例表明如果节点没有被任何subgraph包裹它会被自动归入一个 id 为__swimlane_default__的默认泳道测试断言了g.cluster.swimlane[data-id__swimlane_default__]存在。这解释了为什么在泳道图里裸节点不会渲染失败而是落入一条隐式泳道。节点复用 flowchart 形状语法节点使用 flowchart 风格的形状语法id 写在前面标签写在形状内部最常见的节点形式完整继承自原文档的节点表SyntaxShapeCommon useid[Text]RectangleTask or activityid(Text)Rounded rectangleStep or eventid([Text])StadiumStart or endid{Text}DecisionBranching questionid((Text))CircleConnector or marker完整的形状目录含图标、图片、markdown 字符串、class 与样式选项参见 flowchart 语法文档。样式能力同样完整继承源码补充。swimlanes.spec.ts 中的多个用例证实了以下能力在泳道图中全部可用style A fill:#ff99cc,stroke:#003366,stroke-width:5px,color:#111111—— 节点样式语句linkStyle 0 stroke:#ff6600,stroke-width:5px—— 按序号修饰连线classDef highlighted fill:#bbf,...class A highlighted—— 类定义与类应用且节点会带上highlightedclassthemeVariables如mainBkg、nodeBorder、lineColor—— 主题变量同样生效。此外 handdrawnrough外观也被覆盖测试以look: handDrawn渲染了菱形决策、带标签连线和多泳道 TB 图节点以g.rough-node呈现。连线同泳道与跨泳道连线同样使用 flowchart 风格语法可连接同一泳道内的节点也可跨泳道常见连线形式完整继承自原文档的连线表SyntaxMeaningA -- BArrowA --- BLine without arrowheadA --|Label| BArrow with labelA -.- BDotted arrowA BThick arrow完整连线语法含双向箭头、最小连线长度参见 flowchart 语法的 Links between nodes 一节。跨泳道连线的布局处理源码补充。泳道图最大的布局难点是跨泳道边。从 pipeline.ts 的sugiyamaLayout可以看到布局管线是经典 Sugiyama 四阶段结构且跨泳道边是显式的一等参数const ignoreCrossLaneEdges opts?.ignoreCrossLaneEdges ?? true; // Phase 1: cycle removal const cycleRes removeCycles_DFS(g0); // Phase 2: layering const layering ignoreCrossLaneEdges ? assignLayers_LaneAwareCompact(gAcyclic, {...}) : assignLayers_Gravity(gAcyclic, {...}); // Phase 3: ordering含 laneOrder 优化 const ordered orderLayers(properLayering, graphWithDummies, { laneOrder }); // Phase 4: coordinates const coordinates assignCoordinates(ordered, graphWithDummies, {...});可以推断的默认行为分层layering阶段默认忽略跨泳道边ignoreCrossLaneEdges默认true即跨泳道交接不会破坏各泳道内部的层次紧凑性而是交由 Phase 4 的坐标分配与正交路由器orthogonalRouter/处理走线另有automaticLaneOrdering选项可自动优化泳道排列顺序以减少交叉。该目录下的.ddlt.spec.ts用例如15-border-hugging-lr、7-car-sales-constr与 validateLayout.ts 中的校验逻辑如节点贴边/触碰泳道边框检测表明布局结果有专门的回归校验保障。无障碍标注accTitle 与 accDescr使用accTitle和accDescr提供可访问标题与描述渲染后的 SVG 会携带aria-roledescriptionswimlane见 swimlanes.spec.ts 中assertStandaloneSwimlanesRendered的断言屏幕阅读器可据此识别图表类型再结合accTitle/accDescr提供语义。布局引擎原理泳道图是布局变体图理解泳道图与 flowchart 的关系是理解它为什么语法几乎就是 flowchart的关键。swimlanesDiagram.ts 的头部注释写得很直白// Swimlanes is a layout-variant diagram: it reuses the flowchart parser, DB, // and renderer wholesale and only swaps in a different layout engine // (defaultLayout: swimlane) plus lane-specific styles. export const diagram createFlowDiagram({ defaultLayout: swimlane, styles: swimlanesStyles });即泳道图完整复用 flowchart 的解析器、数据模型和渲染器只替换布局引擎defaultLayout: swimlane并追加泳道专属样式。这是该项目对跨图型隔离规则唯一被允许的例外且只依赖 flowchart 的公开入口createFlowDiagram不触碰其内部。两个直接推论均有测试佐证默认布局优先级flowDiagram.spec.ts 断言defaultLayout如swimlane优先于站点配置的layout值除非用户显式覆盖——所以swimlane-beta图不需要任何额外配置就走泳道布局。样式叠加styles.ts 在 flowchart 全部样式之上追加两条规则.swimlane.cluster rect用主题色clusterBorder画泳道边框主题自适应而非硬编码颜色Neo 外观下关闭 cluster 的模糊滤镜。泳道布局的测试夹具swimlane-beta独立声明保存在 e2e/platform/dev-diagrams/layout-tests/swimlanes 目录包含1-simple、4-car-fun-sales-tb、7-car-sales-constr、8-query-process-2等场景e2e 套件会扫描该目录自动纳入快照回归可用于对照真实布局效果。最佳实践完整继承原文档 Good Practices以下五条实践均直接来自原文档各附其示例。1. 每条泳道只表达一种所有权泳道的选择应回答谁负责这一步除非区分本身正是图的重点否则不要把团队、阶段、状态混在同一条泳道里。2. 为跨泳道交接打标签跨泳道箭头就是责任变化点。当交接依赖某份文档、决策、消息或条件时给箭头加标签。3. 保持长流程可读当泳道或交接点放不进一屏时把大流程拆成多张图。一张好用的泳道图通常不需要把每条箭头追踪两遍就能读懂。4. 使用稳定的 id节点和泳道都用短而有含义的 id。这样标签可以随意改而不会破坏连线、样式或后续引用配合classDef/class尤为明显5. 把决策放在做出决策的泳道里决策节点应放在拥有该决策权的泳道中再把结果路由到执行后续动作的泳道总结泳道图的实现全景维度语法/行为仓库证据图类型识别首行swimlane-beta正则/^\s*swimlane-beta\b/检测detector.ts解析复用 flowchart 词法GRAPH关键词与解析器flow.jison架构布局变体图复用 flowchart parser/DB/renderer仅换布局引擎swimlanesDiagram.ts方向TB/TD/BT/LR/RL默认TBdocs/syntax/swimlanes.md泳道顶层subgraph渲染为g.cluster.swimlane裸节点落入__swimlane_default__默认泳道swimlanes.spec.ts布局Sugiyama 四阶段管线跨泳道边默认不参与分层pipeline.ts样式完整继承style/classDef/linkStyle/主题变量泳道边框主题自适应styles.ts一句话概括泳道图在语法上就是带方向声明的 flowchart 顶层 subgraph 升格为泳道在实现上是 Mermaid 用布局变体模式只换布局引擎、复用解析与渲染交付的一个新图型因此它能天然获得 flowchart 的全部节点形状、连线、样式与主题能力同时由专用的泳道布局管线保证跨泳道交接的排布质量。【免费下载链接】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），仅供参考 Mermaid 泳道图（Swimlanes Diagram）语法详解：从 swimlane-beta 语法到源码级实现原理
Mermaid 泳道图Swimlanes Diagram语法详解从 swimlane-beta 语法到源码级实现原理【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 仓库中的官方语法文档 docs/syntax/swimlanes.md 展开系统讲解泳道图Swimlanes Diagram的完整语法——方向声明、泳道定义、节点形状、连线语法与无障碍标注并结合 swimlanesDiagram.ts 等源码解释布局变体图如何复用 flowchart 解析器与渲染器、泳道布局引擎Sugiyama 管线的工作方式以及默认泳道、主题变量、样式语句在实现中的实际行为。读完本文你可以直接编写生产可用的swimlane-beta图并理解其底层的布局与渲染机制。需要说明的适用前提泳道图是 Mermaid 的新图表类型自v11.16.0引入官方文档明确提示其语法可能在后续版本中演进使用时以当前仓库文档为准。什么是泳道图适合什么场景泳道图将流程按职责切分每条泳道lane代表一个角色、团队、系统或阶段泳道内的节点表示该职责范围内发生的工作箭头表示工作顺序以及跨泳道的交接handoff。官方文档给出的核心判断标准是当你关心的不只是下一步发生什么还有谁负责这一步时就适合用泳道图。典型应用包括审批流程、支持工单处理、交付工作流以及任何工作会跨越团队或系统的流程。与相邻图型的边界引自原文档 When to Use Another Diagram 一节所有权不重要、只需展示顺序或分支 → 用普通 flowchart关注点是在时间轴上参与者之间的消息 → 用 sequenceDiagram关注点是单个事物如何改变状态 → 用 stateDiagram。基本示例官方文档中的第一个完整示例是一个客户 / 客服 / 工程三方支持流程。注意文档提示在线示例渲染使用 Neo 外观与 Redux 主题而开箱即用out of the box的泳道图遵循你配置的默认 look 和 theme这条流程里有两处跨泳道交接客服分诊后按已知问题/需要改代码分叉工程侧修复完成后回到客服的answer节点最终回流到客户的receive节点——这正是泳道图相比普通流程图多表达出来的责任变化点。语法swimlane-beta关键词与方向声明泳道图以swimlane-beta关键词开头其后可选跟一个方向swimlane-betaswimlane-beta LR支持的方向及其含义完整继承自原文档的方向表DirectionMeaningTBTop to bottomTDTop down, same asTBBTBottom to topLRLeft to rightRLRight to left不写方向时默认使用TB。源码印证一解析器层面。在 flow.jison 中swimlane-beta被注册为与graph/flowchart同级的图类型关键词swimlane-beta {if(yy.lex.firstGraph()){this.begin(dir);} return GRAPH;}也就是说swimlane-beta走的正是 flowchart 的词法入口firstGraphdir状态这从机制上解释了为什么它的方向词、节点形状、连线、classDef、style、linkStyle都能直接复用 flowchart 语法。测试 flow.spec.js 也断言了swimlane-beta LR;A--B;可以被解析。源码印证二图类型检测。插件定义在 detector.ts 中检测规则是对文本做正则匹配const detector: DiagramDetector (txt) { return /^\s*swimlane-beta\b/.test(txt); };即文本必须以swimlane-beta开头前导空白允许命中后异步加载swimlanesDiagram.ts。这也意味着swimlane-beta必须出现在文档首行。源码印证三默认方向。e2e 测试 swimlanes.spec.ts 中名为defaults to the swimlanes layout without an explicit layout config的用例验证了不写layout配置时图自动使用泳道布局且每条顶层subgraph都渲染为g.cluster.swimlane元素测试断言了 2 条泳道对应 2 个 cluster。泳道Lanes顶层 subgraph 即泳道在泳道图中顶层 subgraph 被渲染为泳道泳道以end结束。最小示例泳道可以带内部 id 和显示标签这在标签含空格、或需要稳定 id 用于后续样式引用时很有用默认泳道行为源码补充原文档未覆盖。swimlanes.spec.ts 中的puts nodes without an explicit subgraph into a default swimlane用例表明如果节点没有被任何subgraph包裹它会被自动归入一个 id 为__swimlane_default__的默认泳道测试断言了g.cluster.swimlane[data-id__swimlane_default__]存在。这解释了为什么在泳道图里裸节点不会渲染失败而是落入一条隐式泳道。节点复用 flowchart 形状语法节点使用 flowchart 风格的形状语法id 写在前面标签写在形状内部最常见的节点形式完整继承自原文档的节点表SyntaxShapeCommon useid[Text]RectangleTask or activityid(Text)Rounded rectangleStep or eventid([Text])StadiumStart or endid{Text}DecisionBranching questionid((Text))CircleConnector or marker完整的形状目录含图标、图片、markdown 字符串、class 与样式选项参见 flowchart 语法文档。样式能力同样完整继承源码补充。swimlanes.spec.ts 中的多个用例证实了以下能力在泳道图中全部可用style A fill:#ff99cc,stroke:#003366,stroke-width:5px,color:#111111—— 节点样式语句linkStyle 0 stroke:#ff6600,stroke-width:5px—— 按序号修饰连线classDef highlighted fill:#bbf,...class A highlighted—— 类定义与类应用且节点会带上highlightedclassthemeVariables如mainBkg、nodeBorder、lineColor—— 主题变量同样生效。此外 handdrawnrough外观也被覆盖测试以look: handDrawn渲染了菱形决策、带标签连线和多泳道 TB 图节点以g.rough-node呈现。连线同泳道与跨泳道连线同样使用 flowchart 风格语法可连接同一泳道内的节点也可跨泳道常见连线形式完整继承自原文档的连线表SyntaxMeaningA -- BArrowA --- BLine without arrowheadA --|Label| BArrow with labelA -.- BDotted arrowA BThick arrow完整连线语法含双向箭头、最小连线长度参见 flowchart 语法的 Links between nodes 一节。跨泳道连线的布局处理源码补充。泳道图最大的布局难点是跨泳道边。从 pipeline.ts 的sugiyamaLayout可以看到布局管线是经典 Sugiyama 四阶段结构且跨泳道边是显式的一等参数const ignoreCrossLaneEdges opts?.ignoreCrossLaneEdges ?? true; // Phase 1: cycle removal const cycleRes removeCycles_DFS(g0); // Phase 2: layering const layering ignoreCrossLaneEdges ? assignLayers_LaneAwareCompact(gAcyclic, {...}) : assignLayers_Gravity(gAcyclic, {...}); // Phase 3: ordering含 laneOrder 优化 const ordered orderLayers(properLayering, graphWithDummies, { laneOrder }); // Phase 4: coordinates const coordinates assignCoordinates(ordered, graphWithDummies, {...});可以推断的默认行为分层layering阶段默认忽略跨泳道边ignoreCrossLaneEdges默认true即跨泳道交接不会破坏各泳道内部的层次紧凑性而是交由 Phase 4 的坐标分配与正交路由器orthogonalRouter/处理走线另有automaticLaneOrdering选项可自动优化泳道排列顺序以减少交叉。该目录下的.ddlt.spec.ts用例如15-border-hugging-lr、7-car-sales-constr与 validateLayout.ts 中的校验逻辑如节点贴边/触碰泳道边框检测表明布局结果有专门的回归校验保障。无障碍标注accTitle 与 accDescr使用accTitle和accDescr提供可访问标题与描述渲染后的 SVG 会携带aria-roledescriptionswimlane见 swimlanes.spec.ts 中assertStandaloneSwimlanesRendered的断言屏幕阅读器可据此识别图表类型再结合accTitle/accDescr提供语义。布局引擎原理泳道图是布局变体图理解泳道图与 flowchart 的关系是理解它为什么语法几乎就是 flowchart的关键。swimlanesDiagram.ts 的头部注释写得很直白// Swimlanes is a layout-variant diagram: it reuses the flowchart parser, DB, // and renderer wholesale and only swaps in a different layout engine // (defaultLayout: swimlane) plus lane-specific styles. export const diagram createFlowDiagram({ defaultLayout: swimlane, styles: swimlanesStyles });即泳道图完整复用 flowchart 的解析器、数据模型和渲染器只替换布局引擎defaultLayout: swimlane并追加泳道专属样式。这是该项目对跨图型隔离规则唯一被允许的例外且只依赖 flowchart 的公开入口createFlowDiagram不触碰其内部。两个直接推论均有测试佐证默认布局优先级flowDiagram.spec.ts 断言defaultLayout如swimlane优先于站点配置的layout值除非用户显式覆盖——所以swimlane-beta图不需要任何额外配置就走泳道布局。样式叠加styles.ts 在 flowchart 全部样式之上追加两条规则.swimlane.cluster rect用主题色clusterBorder画泳道边框主题自适应而非硬编码颜色Neo 外观下关闭 cluster 的模糊滤镜。泳道布局的测试夹具swimlane-beta独立声明保存在 e2e/platform/dev-diagrams/layout-tests/swimlanes 目录包含1-simple、4-car-fun-sales-tb、7-car-sales-constr、8-query-process-2等场景e2e 套件会扫描该目录自动纳入快照回归可用于对照真实布局效果。最佳实践完整继承原文档 Good Practices以下五条实践均直接来自原文档各附其示例。1. 每条泳道只表达一种所有权泳道的选择应回答谁负责这一步除非区分本身正是图的重点否则不要把团队、阶段、状态混在同一条泳道里。2. 为跨泳道交接打标签跨泳道箭头就是责任变化点。当交接依赖某份文档、决策、消息或条件时给箭头加标签。3. 保持长流程可读当泳道或交接点放不进一屏时把大流程拆成多张图。一张好用的泳道图通常不需要把每条箭头追踪两遍就能读懂。4. 使用稳定的 id节点和泳道都用短而有含义的 id。这样标签可以随意改而不会破坏连线、样式或后续引用配合classDef/class尤为明显5. 把决策放在做出决策的泳道里决策节点应放在拥有该决策权的泳道中再把结果路由到执行后续动作的泳道总结泳道图的实现全景维度语法/行为仓库证据图类型识别首行swimlane-beta正则/^\s*swimlane-beta\b/检测detector.ts解析复用 flowchart 词法GRAPH关键词与解析器flow.jison架构布局变体图复用 flowchart parser/DB/renderer仅换布局引擎swimlanesDiagram.ts方向TB/TD/BT/LR/RL默认TBdocs/syntax/swimlanes.md泳道顶层subgraph渲染为g.cluster.swimlane裸节点落入__swimlane_default__默认泳道swimlanes.spec.ts布局Sugiyama 四阶段管线跨泳道边默认不参与分层pipeline.ts样式完整继承style/classDef/linkStyle/主题变量泳道边框主题自适应styles.ts一句话概括泳道图在语法上就是带方向声明的 flowchart 顶层 subgraph 升格为泳道在实现上是 Mermaid 用布局变体模式只换布局引擎、复用解析与渲染交付的一个新图型因此它能天然获得 flowchart 的全部节点形状、连线、样式与主题能力同时由专用的泳道布局管线保证跨泳道交接的排布质量。【免费下载链接】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），仅供参考