Mermaid 状态图stateDiagram完整语法指南状态、转换、复合状态、并发与样式化实战【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid状态图State Diagram是计算机科学及相关领域用于描述系统行为的一类图它要求被描述的系统由有限数量的状态构成有时是字面事实有时则是合理的抽象。Mermaid 支持将这种基于文本的有限状态机建模为可视化图表其语法尽量与 PlantUML 保持一致以便用户在不同工具之间复用同一份状态图描述。本篇指南以 Mermaid 仓库内官方语法文档 stateDiagram.md对应源文件为 packages/mermaid/src/docs/syntax/stateDiagram.md为骨架展开覆盖状态图从入门到进阶的全部语法要素状态的多种声明方式、转换、开始/结束标记、复合状态、选择、分叉与汇合、便签、并发分区、方向控制、注释以及基于classDef的样式化。读完本文你将能够独立编写从「单状态示例」到「多层嵌套 并发 样式」的完整状态图并在编辑器、文档站或 demos/state.html 等环境中直接运行验证。状态图是什么从最小示例认识两代语法状态图把系统描述为若干states状态以及状态之间如何通过transitions转换相互变化。下面的经典例子包含三个状态Still、Moving与Crash从Still出发可以转入Moving从Moving可以回到Still也可以转入Crash但不存在Still → Crash的转换静止状态下无法崩溃。Mermaid 的注册表里同时保留着两种状态图关键字stateDiagram-v2始终走新一代统一渲染管线dagre-wrapper布局加载实现见 stateDiagram-v2.ts其渲染器指向 stateRenderer-v3-unified.ts最终通过diag.db.getRootDocV2()diag.db.getData()把解析结果转换为通用的布局数据后统一绘制stateDiagram即文档中所说的 Older renderer仍使用 stateRenderer.js 绘制。从检测器源码可以准确看出两种关键字的调度关系stateDetector-V2.ts 会匹配stateDiagram-v2开头的文本同时当配置state.defaultRenderer dagre-wrapper时也会把stateDiagram一并纳入 v2 渲染而 stateDetector.ts 在defaultRenderer被设置为dagre-wrapper时直接返回false不再使用旧渲染器否则匹配stateDiagram进入旧渲染路径。简单说新项目优先使用stateDiagram-v2以获得持续维护的布局与渲染能力。声明状态State的三种写法1. 仅用一个 id 声明最简单的声明方式只给出状态 id2. 使用state关键字 as别名 描述文字3. 使用id : description行内描述语法在解析层面stateDiagram.jison 的state关键字会进入专门的状态机分支既支持带引号字符串再as id的形式也支持不带引号、以:分隔描述的行内写法解析产物统一进入 stateDb.ts 中定义的StateStmt结构字段包含id、description、可选的嵌套doc、note、classes、styles等。转换Transitions与转换标签转换是状态之间流转的「路径/边」用文本箭头--表示如果你在一条转换中引用了尚未定义的状态该状态会以转换中的 id 自动创建之后再补上描述即可转换也可以携带描述文字例如触发条件、事件名写法是在箭头后追加冒号与文本开始与结束状态[*]状态图有两个特殊状态分别表示「开始」与「停止」统一写作[*]箭头指向[*]时它是开始状态箭头离开[*]时它是结束状态——也就是说由转换方向决定其语义在 stateDb.ts 的常量定义中[*]被同时映射为START_NODE/END_NODE并在StateStmt中以start/end两种type区分随后映射为SHAPE_START/SHAPE_END两种形状见 stateCommon.ts分别渲染为实心起点圆和环形终点圆。复合状态Composite States真实世界的系统往往是一张多维的状态网一个状态内部还能容纳若干子状态这类状态在本语法中称为复合状态。定义复合状态需要state关键字 状态 id 花括号{ }包裹的内部子图。复合状态可以像普通状态一样用独立的一行NamedComposite: Another Composite为其命名复合状态支持任意多层嵌套复合状态之间同样可以建立转换一个必须记住的语法边界不能在不同复合状态的内层子状态之间定义转换。从实现上看stateCommon.ts 为嵌套子图准备了独立于整图方向的默认方向常量DEFAULT_NESTED_DOC_DIR默认TB渲染时子文档按各自的复合状态cluster逐层展开整图与子图的方向可以分别控制见下文「方向」一节。选择Choice建模分支逻辑当需要在一个状态之后建模「多选一」的分支时可用choice标记一个状态作为选择点词法层面stateDiagram.jison对choice、fork、join均做了识别并同时兼容旧式[[choice]]、[[fork]]、[[join]]写法解析后这些状态以choice/fork/join类型进入状态图数据模型。分叉与汇合Forks Joins用fork表达一个状态分叉为多条并行分支用join表达多条分支汇合回一条主线便签Notes给图加上补充说明状态图支持在节点旁放置类似 Post-it 的注释可放在节点的右侧或左侧有两种书写方式多行形式note right of State1…end note单行形式note left of State2 : 文本。渲染器会为便签使用独立的形状与连线样式在 stateCommon.ts 中定义了SHAPE_NOTE、SHAPE_NOTEGROUP以及CSS_NOTE_EDGE等常量styles.js 中.state-note、.note-edge等规则可确保便签背景色、边框与虚线引导线都跟随主题变量noteBkgColor、noteBorderColor、noteTextColor。并发Concurrency--分区符与 PlantUML 一致Mermaid 状态图使用--符号把同一个复合状态内部切分成多个并行的子区域。下面用键盘的 NumLock / CapsLock / ScrollLock 三个互不干扰的指示灯来演示「同一复合状态内三条并发子状态机」三个--分隔出的分区在同一个Active复合状态内并行渲染事件EvNumLockPressed等只在各自分区内触发状态切换。这一语法与仓库文档站中专门的 swimlanes.md 主题相对应其解析产物以DIVIDER_TYPE见 stateCommon.ts进入数据模型。设置图的渲染方向direction用direction语句可以控制整体方向支持TB、BT、RL、LR。它还可以写在复合状态内部只影响该子图的方向即使整图为LR其内部子图仍可自行声明方向注意上面示例同时展示了direction语句也兼容stateDiagram旧关键字书写。实现上方向语句被解析为类型dir的语句见 stateDb.ts 的DirectionStmt允许值为TB/BT/RL/LRstateRenderer-v3-unified.ts 中的getDir会逐层扫描每个嵌套文档doc中的dir语句来确定该层方向未显式声明时子文档回退到DEFAULT_NESTED_DOC_DIR。在状态图中写注释Comments状态图支持%%双百分号注释从%%开始到该行结束的所有内容包括任何图语法都会被解析器忽略。注释既可以独占一行也可以放在语句末尾词法层的细节印证了这种「行尾注释」的可行性在 stateDiagram.jison 中%%之后的文本会被跳过而processId()会把 id 字符串内%%之后的内容回退unput给词法分析器继续跳过从而允许注释出现在语句尾部而不污染 id除%%外词法规则还保留了#开头的整行跳过能力作为注释的额外冗余支持。使用 classDef 定制状态样式与流程图等其他图型一致状态图允许在图内用classDef定义命名样式再把它套用到某个/某些状态上。当前的能力边界在状态图上使用classDef有以下已知限制不能应用于开始[*]起点或结束[*]终点状态不能应用于复合状态包含子状态的容器本身或其内部。这两点官方标注为in development预计在后续版本中放开。定义样式的语法classDefclass definition语法为classDef 样式名 一组或多组「CSS 属性 : 值」。单属性示例classDef movement font-style:italic;样式名movement属性/值对font-style取值为italic。多属性时用逗号分隔每一对属性值注意末对之后的分号可省略。三对属性值的完整示例classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow样式名badBadEventfill: #f00、color: white、font-weight: bold、stroke-width: 2px、stroke: yellow。可用的 CSS 属性名称遵循标准 CSS 属性集例如fill填充色、color文字颜色、font-style、font-weight、stroke、stroke-width等。数据模型与词法也都围绕这些关键词做了专门处理STMT_CLASSDEF/STMT_APPLYCLASS常量位于 stateCommon.tscolor/fill/bgFill等专用关键词定义在 stateDb.ts。应用样式的方式一class语句class语句把某个classDef应用到一个或多个状态上语法为class [一个或多个状态名逗号分隔] [classDef 定义的样式名]单状态应用class Crash badBadEvent多状态应用class Moving, Crash movement综合示例注意Crash同时被movement与badBadEvent两个样式叠加应用样式的方式二:::三冒号操作符也可以在转换语句中直接用:::把样式内联到某个状态上语法为[state]:::[style name]它与转换箭头等语句天然融合官方文档注明可用于包括开始与结束状态在内的语句内请在使用的版本中验证边界表现因为上述「限制 1」说明该能力仍处于演进之中此外示例中还出现了accTitle/accDescr两个无障碍指令用于为 SVG 补充可访问标题与描述相关词法在 stateDiagram.jison 中通过acc_title、acc_descr、acc_descr_multiline三个词法状态实现。状态名中的空格Spaces in state names状态 id 不能直接包含空格但可以通过「先以 id 定义带描述状态、之后再引用该 id」的方式来显示带空格的标签。下面的示例定义了一个 id 为yswsii、显示文本为Your state with spaces in it的状态随后在[*] -- yswsii与yswsii -- YetAnotherState两处引用它并用yourState样式把它与其他状态区分开源码级速览一张状态图的生命周期把以上语法放入实现语境可以得到一张图的完整处理链均可在仓库内对应文件验证探测与加载按文本开头选择stateDiagram-v2或stateDiagram检测逻辑见 stateDetector-V2.ts 与 stateDetector.ts图定义见 stateDiagram-v2.ts / stateDiagram.ts。词法与语法分析stateDiagram.jison 完成 token 化与规则归约覆盖本文出现的全部语句类型状态、转换、方向、classDef、class、note、--分区、fork/join/choice等其%lex段同时处理%%/#注释、direction大小写不敏感识别与accTitle等指令。数据模型语句被规约为类型联合Stmt见 stateDb.ts支持按嵌套doc表达复合/并发结构stateCommon.ts 集中定义形状名、方向默认值、CSS 类名与图内常量。布局与渲染v2 走 stateRenderer-v3-unified.ts 将图数据交给统一渲染管线旧版走 stateRenderer.js。两种渲染器共用 styles.js 输出的样式串其中颜色/圆角/粗细全部来自主题选项如transitionColor、stateLabelColor、stateBorder、noteBkgColor、compositeBackground等因此状态图可以无缝跟随 Mermaid 的默认/暗色等主题。验证用例仓库在 state 目录 下提供成体系测试包括语法级 state-parser.spec.js 与 state-style.spec.js、数据层 stateDb.spec.js、整图渲染层 stateDiagram-v2.spec.js、stateDiagram.spec.js 与 stateRenderer.spec.js端到端快照用例可参考 e2e/diagrams/state-diagram-v2 与 e2e/diagrams/state-diagram 目录下的大量.mmd样例。如果想要快速在浏览器里验证上述任一段语法可以直接打开仓库中的 demos/state.html 把代码粘贴进去预览更详尽的语法示例也可对照 docs/syntax/stateDiagram.md 的在线版本。掌握了状态、转换、复合状态、并发、注释与classDef样式这六大模块你就拥有了把任何「有限状态机」需求翻译成可维护文本图表的核心能力。【免费下载链接】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 状态图（stateDiagram）完整语法指南：状态、转换、复合状态、并发与样式化实战
Mermaid 状态图stateDiagram完整语法指南状态、转换、复合状态、并发与样式化实战【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid状态图State Diagram是计算机科学及相关领域用于描述系统行为的一类图它要求被描述的系统由有限数量的状态构成有时是字面事实有时则是合理的抽象。Mermaid 支持将这种基于文本的有限状态机建模为可视化图表其语法尽量与 PlantUML 保持一致以便用户在不同工具之间复用同一份状态图描述。本篇指南以 Mermaid 仓库内官方语法文档 stateDiagram.md对应源文件为 packages/mermaid/src/docs/syntax/stateDiagram.md为骨架展开覆盖状态图从入门到进阶的全部语法要素状态的多种声明方式、转换、开始/结束标记、复合状态、选择、分叉与汇合、便签、并发分区、方向控制、注释以及基于classDef的样式化。读完本文你将能够独立编写从「单状态示例」到「多层嵌套 并发 样式」的完整状态图并在编辑器、文档站或 demos/state.html 等环境中直接运行验证。状态图是什么从最小示例认识两代语法状态图把系统描述为若干states状态以及状态之间如何通过transitions转换相互变化。下面的经典例子包含三个状态Still、Moving与Crash从Still出发可以转入Moving从Moving可以回到Still也可以转入Crash但不存在Still → Crash的转换静止状态下无法崩溃。Mermaid 的注册表里同时保留着两种状态图关键字stateDiagram-v2始终走新一代统一渲染管线dagre-wrapper布局加载实现见 stateDiagram-v2.ts其渲染器指向 stateRenderer-v3-unified.ts最终通过diag.db.getRootDocV2()diag.db.getData()把解析结果转换为通用的布局数据后统一绘制stateDiagram即文档中所说的 Older renderer仍使用 stateRenderer.js 绘制。从检测器源码可以准确看出两种关键字的调度关系stateDetector-V2.ts 会匹配stateDiagram-v2开头的文本同时当配置state.defaultRenderer dagre-wrapper时也会把stateDiagram一并纳入 v2 渲染而 stateDetector.ts 在defaultRenderer被设置为dagre-wrapper时直接返回false不再使用旧渲染器否则匹配stateDiagram进入旧渲染路径。简单说新项目优先使用stateDiagram-v2以获得持续维护的布局与渲染能力。声明状态State的三种写法1. 仅用一个 id 声明最简单的声明方式只给出状态 id2. 使用state关键字 as别名 描述文字3. 使用id : description行内描述语法在解析层面stateDiagram.jison 的state关键字会进入专门的状态机分支既支持带引号字符串再as id的形式也支持不带引号、以:分隔描述的行内写法解析产物统一进入 stateDb.ts 中定义的StateStmt结构字段包含id、description、可选的嵌套doc、note、classes、styles等。转换Transitions与转换标签转换是状态之间流转的「路径/边」用文本箭头--表示如果你在一条转换中引用了尚未定义的状态该状态会以转换中的 id 自动创建之后再补上描述即可转换也可以携带描述文字例如触发条件、事件名写法是在箭头后追加冒号与文本开始与结束状态[*]状态图有两个特殊状态分别表示「开始」与「停止」统一写作[*]箭头指向[*]时它是开始状态箭头离开[*]时它是结束状态——也就是说由转换方向决定其语义在 stateDb.ts 的常量定义中[*]被同时映射为START_NODE/END_NODE并在StateStmt中以start/end两种type区分随后映射为SHAPE_START/SHAPE_END两种形状见 stateCommon.ts分别渲染为实心起点圆和环形终点圆。复合状态Composite States真实世界的系统往往是一张多维的状态网一个状态内部还能容纳若干子状态这类状态在本语法中称为复合状态。定义复合状态需要state关键字 状态 id 花括号{ }包裹的内部子图。复合状态可以像普通状态一样用独立的一行NamedComposite: Another Composite为其命名复合状态支持任意多层嵌套复合状态之间同样可以建立转换一个必须记住的语法边界不能在不同复合状态的内层子状态之间定义转换。从实现上看stateCommon.ts 为嵌套子图准备了独立于整图方向的默认方向常量DEFAULT_NESTED_DOC_DIR默认TB渲染时子文档按各自的复合状态cluster逐层展开整图与子图的方向可以分别控制见下文「方向」一节。选择Choice建模分支逻辑当需要在一个状态之后建模「多选一」的分支时可用choice标记一个状态作为选择点词法层面stateDiagram.jison对choice、fork、join均做了识别并同时兼容旧式[[choice]]、[[fork]]、[[join]]写法解析后这些状态以choice/fork/join类型进入状态图数据模型。分叉与汇合Forks Joins用fork表达一个状态分叉为多条并行分支用join表达多条分支汇合回一条主线便签Notes给图加上补充说明状态图支持在节点旁放置类似 Post-it 的注释可放在节点的右侧或左侧有两种书写方式多行形式note right of State1…end note单行形式note left of State2 : 文本。渲染器会为便签使用独立的形状与连线样式在 stateCommon.ts 中定义了SHAPE_NOTE、SHAPE_NOTEGROUP以及CSS_NOTE_EDGE等常量styles.js 中.state-note、.note-edge等规则可确保便签背景色、边框与虚线引导线都跟随主题变量noteBkgColor、noteBorderColor、noteTextColor。并发Concurrency--分区符与 PlantUML 一致Mermaid 状态图使用--符号把同一个复合状态内部切分成多个并行的子区域。下面用键盘的 NumLock / CapsLock / ScrollLock 三个互不干扰的指示灯来演示「同一复合状态内三条并发子状态机」三个--分隔出的分区在同一个Active复合状态内并行渲染事件EvNumLockPressed等只在各自分区内触发状态切换。这一语法与仓库文档站中专门的 swimlanes.md 主题相对应其解析产物以DIVIDER_TYPE见 stateCommon.ts进入数据模型。设置图的渲染方向direction用direction语句可以控制整体方向支持TB、BT、RL、LR。它还可以写在复合状态内部只影响该子图的方向即使整图为LR其内部子图仍可自行声明方向注意上面示例同时展示了direction语句也兼容stateDiagram旧关键字书写。实现上方向语句被解析为类型dir的语句见 stateDb.ts 的DirectionStmt允许值为TB/BT/RL/LRstateRenderer-v3-unified.ts 中的getDir会逐层扫描每个嵌套文档doc中的dir语句来确定该层方向未显式声明时子文档回退到DEFAULT_NESTED_DOC_DIR。在状态图中写注释Comments状态图支持%%双百分号注释从%%开始到该行结束的所有内容包括任何图语法都会被解析器忽略。注释既可以独占一行也可以放在语句末尾词法层的细节印证了这种「行尾注释」的可行性在 stateDiagram.jison 中%%之后的文本会被跳过而processId()会把 id 字符串内%%之后的内容回退unput给词法分析器继续跳过从而允许注释出现在语句尾部而不污染 id除%%外词法规则还保留了#开头的整行跳过能力作为注释的额外冗余支持。使用 classDef 定制状态样式与流程图等其他图型一致状态图允许在图内用classDef定义命名样式再把它套用到某个/某些状态上。当前的能力边界在状态图上使用classDef有以下已知限制不能应用于开始[*]起点或结束[*]终点状态不能应用于复合状态包含子状态的容器本身或其内部。这两点官方标注为in development预计在后续版本中放开。定义样式的语法classDefclass definition语法为classDef 样式名 一组或多组「CSS 属性 : 值」。单属性示例classDef movement font-style:italic;样式名movement属性/值对font-style取值为italic。多属性时用逗号分隔每一对属性值注意末对之后的分号可省略。三对属性值的完整示例classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow样式名badBadEventfill: #f00、color: white、font-weight: bold、stroke-width: 2px、stroke: yellow。可用的 CSS 属性名称遵循标准 CSS 属性集例如fill填充色、color文字颜色、font-style、font-weight、stroke、stroke-width等。数据模型与词法也都围绕这些关键词做了专门处理STMT_CLASSDEF/STMT_APPLYCLASS常量位于 stateCommon.tscolor/fill/bgFill等专用关键词定义在 stateDb.ts。应用样式的方式一class语句class语句把某个classDef应用到一个或多个状态上语法为class [一个或多个状态名逗号分隔] [classDef 定义的样式名]单状态应用class Crash badBadEvent多状态应用class Moving, Crash movement综合示例注意Crash同时被movement与badBadEvent两个样式叠加应用样式的方式二:::三冒号操作符也可以在转换语句中直接用:::把样式内联到某个状态上语法为[state]:::[style name]它与转换箭头等语句天然融合官方文档注明可用于包括开始与结束状态在内的语句内请在使用的版本中验证边界表现因为上述「限制 1」说明该能力仍处于演进之中此外示例中还出现了accTitle/accDescr两个无障碍指令用于为 SVG 补充可访问标题与描述相关词法在 stateDiagram.jison 中通过acc_title、acc_descr、acc_descr_multiline三个词法状态实现。状态名中的空格Spaces in state names状态 id 不能直接包含空格但可以通过「先以 id 定义带描述状态、之后再引用该 id」的方式来显示带空格的标签。下面的示例定义了一个 id 为yswsii、显示文本为Your state with spaces in it的状态随后在[*] -- yswsii与yswsii -- YetAnotherState两处引用它并用yourState样式把它与其他状态区分开源码级速览一张状态图的生命周期把以上语法放入实现语境可以得到一张图的完整处理链均可在仓库内对应文件验证探测与加载按文本开头选择stateDiagram-v2或stateDiagram检测逻辑见 stateDetector-V2.ts 与 stateDetector.ts图定义见 stateDiagram-v2.ts / stateDiagram.ts。词法与语法分析stateDiagram.jison 完成 token 化与规则归约覆盖本文出现的全部语句类型状态、转换、方向、classDef、class、note、--分区、fork/join/choice等其%lex段同时处理%%/#注释、direction大小写不敏感识别与accTitle等指令。数据模型语句被规约为类型联合Stmt见 stateDb.ts支持按嵌套doc表达复合/并发结构stateCommon.ts 集中定义形状名、方向默认值、CSS 类名与图内常量。布局与渲染v2 走 stateRenderer-v3-unified.ts 将图数据交给统一渲染管线旧版走 stateRenderer.js。两种渲染器共用 styles.js 输出的样式串其中颜色/圆角/粗细全部来自主题选项如transitionColor、stateLabelColor、stateBorder、noteBkgColor、compositeBackground等因此状态图可以无缝跟随 Mermaid 的默认/暗色等主题。验证用例仓库在 state 目录 下提供成体系测试包括语法级 state-parser.spec.js 与 state-style.spec.js、数据层 stateDb.spec.js、整图渲染层 stateDiagram-v2.spec.js、stateDiagram.spec.js 与 stateRenderer.spec.js端到端快照用例可参考 e2e/diagrams/state-diagram-v2 与 e2e/diagrams/state-diagram 目录下的大量.mmd样例。如果想要快速在浏览器里验证上述任一段语法可以直接打开仓库中的 demos/state.html 把代码粘贴进去预览更详尽的语法示例也可对照 docs/syntax/stateDiagram.md 的在线版本。掌握了状态、转换、复合状态、并发、注释与classDef样式这六大模块你就拥有了把任何「有限状态机」需求翻译成可维护文本图表的核心能力。【免费下载链接】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），仅供参考