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本文基于 Mermaid 官方语法文档 docs/syntax/flowchart.md 编写系统讲解 Mermaid 流程图flowchart的完整语法体系从节点与边的基本定义、全部传统节点形状到 v11.3.0 引入的 30 余种扩展形状shape:元数据语法与icon/image特殊形状再到边类型、子图含 v11.17.0 的折叠子图、样式与 class、点击交互、字体图标及渲染器配置。读完后你可以独立编写生产级流程图并理解其背后源码中的形状注册与解析机制。1. 流程图的基本构成流程图由节点几何形状和边箭头或连线组成。Mermaid 代码定义节点和边如何创建支持不同的箭头类型、双向箭头以及指向子图与来自子图的任意连线。在编写流程图之前官方文档特别强调两个常见的语法陷阱警告如果你在节点中使用单词end请整个单词或其中任意字母大写如End或END。全小写的end会破坏流程图的解析end是子图的结束关键字。警告如果连接线的右侧节点以字母o或x开头请在该字母前加空格或将其大写例如dev--- ops、dev---Ops。因为A---oB会被解析为圆圈端点边A---xB会被解析为叉形端点边。1.1 默认节点最简单的节点只需给出一个 idid 会直接显示在方框中提示flowchart关键字也可以用graph代替两者等价。1.2 带文本的节点可以让节点显示的文本与 id 不同。如果对同一节点多次定义文本渲染时使用最后一次找到的文本之后若只为该节点定义边也可以省略文本定义Unicode 文本使用双引号包裹 Unicode 文本Markdown 格式化使用双引号加反引号text包裹 Markdown 文本可启用粗体、斜体与换行该配置中htmlLabels: false表示以 SVG 文本而非 HTML渲染标签。2. 方向声明Direction方向语句声明流程图的整体流向支持的全部方向取值方向含义TBTop to bottom自上而下TDTop-down等同于TBBTBottom to top自下而上RLRight to left自右向左LRLeft to right自左向右3. 传统节点形状Node shapes下表汇总官方文档中列出的全部传统形状语法形状语法示例默认矩形id1或id1[Text]圆角矩形id1(This is the text)体育场形stadiumid1([This is the text])子程序形id1[[This is the text]]圆柱形数据库id1[(Database)]圆形id1((This is the text in the circle))非对称形id1This is the text]菱形判断id1{This is the text}六边形id1{{This is the text}}平行四边形id1[/Text/]平行四边形反向id1[\Text\]梯形A[/Christmas\]梯形反向B[\Go shopping/]双圆形id1(((Text)))各形状的独立示例官方文档说明非对称形状目前只支持text]这一种形态尚不支持其镜像写法未来版本可能改变。4. 扩展节点形状v11.3.0从 v11.3.0 开始Mermaid 引入 30 多种新形状用于更精确地表达流程中的过程、判断、事件、数据存储等语义元素。新形状采用通用的元数据语法定义A{ shape: rect }该语法把节点 A 渲染为矩形效果与A[A]或A一致但语义更清晰。4.1 完整形状列表以下为文档给出的完整对照表语义名 / 形状名 / 短名 / 说明 / 支持的别名语义名形状名短名说明支持的别名BangBangbangBangbangBrowserBrowserbrowser浏览器窗口BucketBucketbucket对象存储桶CardNotched Rectanglenotch-rect表示一张卡片card、notched-rectangleCloudCloudcloud云cloudCollateHourglasshourglass表示合并collate操作collate、hourglassCom LinkLightning Boltbolt通信链路com-link、lightning-boltCommentCurly Bracebrace添加注释brace-l、commentComment RightCurly Bracebrace-r添加注释Comment with braces on both sidesCurly Bracesbraces添加注释ConsoleConsole (terminal window)console终端窗口Data Input/OutputLean Rightlean-r表示输入或输出in-out、lean-rightData Input/OutputLean Leftlean-l表示输出或输入lean-left、out-inData StoreData Storedatastore数据流图中的数据存储data-storeDatabaseCylindercyl数据库存储cylinder、database、dbDecisionDiamonddiam决策步骤decision、diamond、questionDelayHalf-Rounded Rectangledelay表示延时half-rounded-rectangleDirect Access StorageHorizontal Cylinderh-cyl直接存取存储das、horizontal-cylinderDisk StorageLined Cylinderlin-cyl磁盘存储disk、lined-cylinderDisplayCurved Trapezoidcurv-trap表示显示设备curved-trapezoid、displayDivided ProcessDivided Rectanglediv-rect分隔过程形div-proc、divided-process、divided-rectangleDocumentDocumentdoc表示文档doc、documentEventRounded Rectanglerounded表示事件eventExtractTriangletri提取过程extract、triangleFolderFolderfolder文件夹或目录directoryFork/JoinFilled Rectanglefork流程中的分支或汇合joinInternal StorageWindow Panewin-pane内部存储internal-storage、window-paneJunctionFilled Circlef-circ连接点filled-circle、junctionLined DocumentLined Documentlin-doc带线文档lined-documentLined/Shaded ProcessLined Rectanglelin-rect带线过程形lin-proc、lined-process、lined-rectangle、shaded-processLoop LimitTrapezoidal Pentagonnotch-pent循环限制步骤loop-limit、notched-pentagonManual FileFlipped Triangleflip-tri手工文件操作flipped-triangle、manual-fileManual InputSloped Rectanglesl-rect手工输入步骤manual-input、sloped-rectangleManual OperationTrapezoid Base Toptrap-t表示手工任务inv-trapezoid、manual、trapezoid-topMulti-DocumentStacked Documentdocs多个文档documents、st-doc、stacked-documentMulti-ProcessStacked Rectanglest-rect多个过程processes、procs、stacked-rectangleOddOddodd特殊形状Paper TapeFlagflag纸带paper-tapePersonPersonperson人圆头加圆角身体Prepare ConditionalHexagonhex准备或条件步骤hexagon、preparePriority ActionTrapezoid Base Bottomtrap-b优先操作priority、trapezoid、trapezoid-bottomProcessRectanglerect标准过程形proc、process、rectangleStartCirclecircle起点circStartSmall Circlesm-circ小起点small-circle、startStopDouble Circledbl-circ表示停止点double-circleStopFramed Circlefr-circ停止点framed-circle、stopStored DataBow Tie Rectanglebow-rect存储数据bow-tie-rectangle、stored-dataSubprocessFramed Rectanglefr-rect子过程framed-rectangle、subproc、subprocess、subroutineSummaryCrossed Circlecross-circ汇总crossed-circle、summaryTagged DocumentTagged Documenttag-doc带标签文档tag-doc、tagged-documentTagged ProcessTagged Rectangletag-rect带标签过程tag-proc、tagged-process、tagged-rectangleTerminal PointStadiumstadium终点pill、terminalText BlockText Blocktext文本块4.2 综合示例4.3 常见新形状示例4.4 源码印证形状是如何注册的从源码结构看扩展形状的实现位于统一渲染工具中。shapes.ts 顶部集中导入了每个形状的渲染实现如bowTieRect.js、bucket.js、flippedTriangle.js、hourglass.js、lightningBolt.js、trapezoidalPentagon.js、windowPane.js等与文档表格中的形状一一对应说明新形状遵循“每个形状一个渲染函数 中央注册表”的组织方式。形状名称在渲染前会经过校验flowDb.ts 中在设置节点形状时如果shape名称不是小写会抛出No such shape: ... Shape names should be lowercase.错误找不到对应形状时抛出No such shape: ...。这就是为什么文档要求形状名一律使用小写短名或别名。5. 特殊形状icon 与 imagev11.3.0除常规几何形状外Mermaid 还支持两种特殊形状icon和image可在流程图中直接嵌入图标与图片。5.1 Icon 形状使用icon形状嵌入图标前需要先注册图标包参见 icons.md 的说明。语法示例参数说明icon已注册图标包中的图标名form图标的背景形状不定义则图标无背景。可选square、circle、roundedlabel图标关联的文本标签任意字符串不定义则不显示标签pos标签位置不定义时默认在图标底部。可选t、bh图标高度不定义时默认为最小值 48。5.2 Image 形状使用img键引用图片 URL参数说明img要显示的图片 URLlabel图片关联的文本标签不定义则不显示pos标签位置不定义时默认在图片底部。可选t、bw图片宽度不定义时使用图片自然宽度h图片高度不定义时使用图片自然高度constraint是否约束节点尺寸。设为on时同时保证图片保持原始宽高比并按高度h等比调整宽度w。不定义时默认off。可选on、off。如果只想按比例缩放图片设置h并令constraint: on即可6. 节点之间的边Links between nodes节点通过边/连线连接Mermaid 支持多种边类型也可为边附加文本。6.1 基本边类型不带箭头的开放连线边上带文本两种写法带箭头的边加文本两种写法虚线边带文本的虚线边粗边带文本的粗边6.2 不可见边不可见边在需要调整节点默认布局位置时很有用6.3 链接链Chaining可以在同一行声明多条边也可以在同一行声明多组节点的链接运算符可以表达“笛卡尔积”式的依赖关系例如一行A B-- C D等价于原文文档在此处也提醒过度使用表达式会让 Markdown 源码更难阅读——“瑞典语 lagom不多不少刚刚好”。6.4 为边指定 IDAttaching an ID to Edges类似节点可以携带 id 与元数据边现在也支持 id在边语法前加id。这里e1是连接 A 到 B 的边的 ID之后可以在样式或 class 定义中使用它。6.5 边的动画Animation为边指定 ID 后可以通过定义边的属性开启动画这表示边e1需要动画。初始版本支持两种动画速度fast和slow选择动画类型是“启用动画 设置速度”的简写等价于{ animate: true, animation: fast }。也可以借助classDef为边加动画类其中e1--创建带 IDe1的边classDef animate定义名为animate的样式类含动画属性class e1 animate把该类应用到边e1。注意设置stroke-dasharray时逗号要转义为\,因为逗号在 Mermaid 样式定义中用作分隔符。6.6 新型箭头圆圈端点与叉形端点圆圈端点边叉形端点边6.7 多方向箭头6.8 边的最小长度Minimum length of a link流程图中每个节点最终会被分配到渲染图中的某个 rank即按方向划分的垂直或水平层级。默认情况下边可以跨越任意数量的 rank但可以通过在边定义中增加额外的短横线让某条边比其他的更长。下例中 B 到 E 的链接多加了两个短横线使其比普通链接多跨两个 rank注意渲染引擎为了满足其他约束仍可能把边画得比要求的 rank 数更长。当标签写在边中间时额外的短横线要加在右侧对于虚线与粗线要增加的是点号或等号完整对照表如下长度123普通------------带箭头的普通---------粗线带箭头的粗线虚线-.--..--...-带箭头的虚线-.--..--...-7. 特殊字符与转义用引号包裹文本可以渲染更复杂的字符实体编码转义支持使用实体编码转义字符十进制数字或 HTML 字符名数字按十进制给出例如#可以编码为#35;HTML 字符名同样受支持。8. 子图Subgraphs基本结构subgraph title graph definition end完整示例也可以为子图显式指定 id8.1 指向子图的边在flowchart图中可以定义指向子图或来自子图的边8.2 子图内的方向Direction in subgraphs使用direction语句设置子图的渲染方向限制Limitation如果子图内的任意节点与外部相连该子图的direction将被忽略子图转而继承父图的方向即链接指向子图本身时方向得以保留链接指向子图内部节点时方向被父图覆盖。8.3 可折叠子图Collapsible subgraphsv11.17.0通过给子图 id 附加元数据{ view: collapsed }可以把子图折叠为一个紧凑节点用于隐藏分组内部细节、同时保留它与图其余部分的连接关系元数据通过既有id{ ... }语句语法附加id即子图 id使用subgraph id [Title]为子图显式命名。子图被折叠时内部节点被隐藏整体绘制为携带子图标题的单个节点跨越子图边界的边被重定向到折叠节点完全位于折叠子图内部的边会被丢弃否则会成为折叠节点上的自环对于嵌套子图折叠会解析到最外层的折叠祖先——指向深层嵌套节点的边将落在最外层折叠分组上。view: expanded是默认行为正常渲染子图省略元数据或显式设置view: expanded均保持原有行为。9. Markdown 字符串Markdown StringsMarkdown 字符串是一种更灵活的字符串类型支持粗体、斜体等格式并会自动换行同时适用于节点标签、边标签和子图标签格式化规则粗体文本前后各加两个星号**斜体文本前后各加一个星号*传统字符串需要br标签才能换行而 Markdown 字符串在文本过长时自动换行并且可以直接使用换行符开始新的一行无需br标签。自动换行可以通过配置禁用--- config: markdownAutoWrap: false --- graph LR10. 交互Interaction可以把点击事件绑定到节点点击可以触发 JavaScript 回调也可以在新标签页中打开链接。注意该功能在securityLevelstrict下被禁用在securityLevelloose下启用。基本语法click nodeId callback click nodeId call callback()nodeId是节点 idcallback是显示该图的页面上定义的 JavaScript 函数名调用时会以 nodeId 作为参数传入。页面端定义回调script window.callback function () { alert(A callback was triggered); }; /script工具提示tooltip文本用双引号包裹样式由.mermaidTooltip类控制提示tooltip 功能与 URL 链接能力从 0.5.2 版本开始可用。链接默认在同一标签页/窗口打开。可以在 click 定义中追加 link target 修改这一行为支持_self、_blank、_parent、_top完整 HTML 使用示例body pre classmermaid flowchart LR A--B B--C C--D click A callback Tooltip click B https://www.github.com This is a link click C call callback() Tooltip click D href https://www.github.com This is a link /pre script window.callback function () { alert(A callback was triggered); }; const config { startOnLoad: true, htmlLabels: true, flowchart: { useMaxWidth: true, curve: cardinal }, securityLevel: loose, }; mermaid.initialize(config); /script /body注释Comments流程图内可以写注释解析器会忽略它们。注释必须独占一行且以%%开头从注释标记到行尾的所有内容包括流程图语法都视为注释11. 样式与类Styling and classes11.1 为边设置样式边不像节点那样有 id因此按“边在图中被定义时的顺序号”来指定样式或用default应用到所有边。下例中linkStyle的样式作用于图中的第 4 条边linkStyle 3 stroke:#ff3,stroke-width:4px,color:red;也可以一条语句为多条边加样式边序号用逗号分隔linkStyle 1,2,7 color:blue;注意6.4 节中为边分配 ID 后也能通过 class 机制直接针对某条边设置样式两种机制可组合使用。11.2 曲线样式Styling line curves如果默认曲线不满足需求可以调整连线使用的曲线类型。可用的曲线样式包括basis、bumpX、bumpY、cardinal、catmullRom、linear、monotoneX、monotoneY、natural、step、stepAfter、stepBefore完整列表与自定义曲线可参考 d3-shape 的 Shapes 文档。图级曲线样式--- config: flowchart: curve: stepBefore --- graph LR边级曲线样式v11.10.0为边分配 ID 后可以用curve属性单独修改其曲线边级曲线样式覆盖图级样式同一条边被多次修改时最后一次修改生效。11.3 为节点设置样式可以对节点应用加粗边框、不同背景色等样式11.4 Classes相比每次写style更推荐定义样式类并挂载到节点上classDef className fill:#f9f,stroke:#333,stroke-width:4px;一条语句也可定义多个类classDef firstClassName,secondClassName font-size:12pt;把类挂到节点上class nodeId1 className;一条语句挂多个节点class nodeId1,nodeId2 className;更简短的形式是用:::操作符直接把类名附加到节点上声明多条链接时同样可用11.5 关于外部 CSS 类的重要提醒通过外部 CSS例如.cssClass rect { fill: ... }给 Mermaid 节点加样式不可靠。Mermaid 的内部样式以!important注入并作用域限定到 SVG 元素 ID优先级高于外部 CSS 规则外部 CSS 会被静默覆盖。推荐做法就是上面的classDef语法——它是预期的样式机制。如果确实必须使用外部 CSS每个属性都得加!important但不推荐11.6 默认类Default class名为default的类会被自动分配给所有没有指定类的节点classDef default fill:#f9f,stroke:#333,stroke-width:4px;12. FontAwesome 图标支持可以通过fa:#icon class name#语法在节点中使用 FontAwesome 图标两种显示方式12.1 注册 FontAwesome 图标包v11.7.0按照 icons.md 中“注册图标包”的说明可以注册自己的 FontAwesome 图标包。支持的前缀fa、fab、fas、far、fal、fad。注意如果没有注册 FontAwesome 包会回退到 FontAwesome CSS 方案。12.2 注册 FontAwesome CSS只要网站引入了 Font Awesome 的 CSSMermaid 就支持 Font Awesome且不限制 Font Awesome 版本。在head中加入如下片段即可支持 Font Awesome v6.5.1link hrefhttps://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css relstylesheet /12.3 自定义图标只要网站导入了对应的 kit就可以使用作为 Font Awesome 提供的自定义图标注意这目前是 Font Awesome 的付费功能。自定义图标需要使用fak前缀flowchart TD B[fa:fa-twitter] %% standard icon B--E(fak:fa-custom-icon-name) %% custom icon13. 声明语法细节从 0.2.16 版本起图声明语句末尾的分号是可选的顶点与链接之间允许存在单个空格但顶点与其文本之间、链接与其文本之间不能有空格旧语法依然有效新写法是为提升可读性而引入的可选特性。14. 配置Configuration14.1 渲染器Renderer图的布局由渲染器完成默认渲染器是dagre。从 Mermaid 9.4 版本开始可以使用另一个名为elk的渲染器它更适合大型和/或更复杂的图。elk 渲染器是实验特性通过以下指令启用config: flowchart: defaultRenderer: elk注意站点需要使用 9.4 版本的 mermaid且在懒加载lazy-loading配置中启用该特性。从仓库源码看elk 渲染路径独立存在于 elk/ 目录含 detector.ts 等文件与默认 dagre 渲染并行e2e 测试中也有专门的 ELK 快照目录 e2e/diagrams/flowchart/elk可用于对照两种渲染器的布局差异。14.2 宽度Width可以调整渲染后流程图的宽度通过设置mermaid.flowchartConfig或在 CLI 中使用 JSON 配置文件CLI 用法参见 mermaidCLI.md。mermaid.flowchartConfig可以设为包含配置参数的 JSON 字符串或对象mermaid.flowchartConfig { width: 100% }15. 小结与延伸阅读本文覆盖了 docs/syntax/flowchart.md 的全部语法主题节点与文本、方向、传统形状、v11.3.0 扩展形状与icon/image特殊形状、边的全部变体含不可见边、链接链、边 ID、动画、圆圈/叉形端点、最小长度、特殊字符转义、子图含方向限制与 v11.17.0 折叠子图、Markdown 字符串、点击交互与注释、样式/class/CSS 陷阱、FontAwesome 图标、声明语法细节以及渲染器与宽度配置。如需继续深入可参考仓库中的相关资源形状注册与实现的源码入口packages/mermaid/src/rendering-util/rendering-elements/shapes.ts流程图数据库节点/边/形状/折叠子图的内部状态packages/mermaid/src/diagrams/flowchart/flowDb.ts统一渲染器与 v2 解析器packages/mermaid/src/diagrams/flowchart/flowRenderer-v3-unified.ts、packages/mermaid/src/diagrams/flowchart/flowDetector-v2.ts图标注册的配置说明docs/config/icons.mde2e 流程图测试用例可验证本文各语法特性e2e/diagrams/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），仅供参考