illegalCreed

中文

English

中文

English

Appearance

参考：图类型 / 形状 / 箭头 / 基数 / 配置速查 ​

基于 Mermaid v11.16.0（npm latest 实测）· 核于 2026-07

速查 ​

  • 图类型声明关键字（首行决定一切）：
    • 八大常用图：flowchart（旧 graph）/ sequenceDiagram / classDiagram / stateDiagram-v2 / erDiagram / gantt / pie / gitGraph
    • 更多图类型：mindmap / timeline / quadrantChart / sankey-beta / xychart / block-beta / architecture-beta / packet-beta / kanban / radar-beta / journey / requirementDiagram / C4Context / zenuml / treemap
  • flowchart 方向：TB（=TD）/ BT / LR / RL；节点 = id + 包裹符号定形状，同 id 可复用、文本只需声明一次
  • flowchart 连线速记：--> 实箭、--- 实线、-.-> 虚箭、==> 粗箭、~~~ 隐形（只参与布局）、--o/--x 圆头/叉头、<--> 双向、& 并联展开一对多
  • v11.3+ 统一形状语法：@{ shape: rect | diamond | cyl | doc | stadium | hourglass | bolt | ... } 一举扩到 30+ 形状；另有 @{ icon: "fa:..." } / @{ img: "url" } 节点
  • flowchart 曲线：curve: basis | linear | cardinal | monotoneX | step | stepBefore | stepAfter
  • sequence 消息箭头：->/--> 无箭头、->>/-->> 实心箭头（请求/响应惯用）、<<->>/<<-->> 双向（v11.0+）、-x/--x 失败带叉、-)/--) 异步开箭头
  • sequence 控制块：loop / alt+else / opt / par+and / critical+option / break，全部以 end 收尾、可嵌套
  • class 关系箭头八件套：
    • <|-- 继承（空心三角指父类）、..|> 实现（虚线空心三角指接口）
    • *-- 组合（实心菱形在整体侧，部分不可独立存活）、o-- 聚合（空心菱形在整体侧，部分可独立）
    • --> 关联、..> 依赖（虚线）、--/.. 无方向连接线（实/虚）
  • class 可见性/修饰：+/-/#/~ 分别对应 public/private/protected/package；* 抽象方法、$ 静态方法或字段
  • er 基数四对（符号靠近哪侧就说明哪侧数量）：|o/o| 零或一、||/|| 恰好一、}o/o{ 零或多、}|/|{ 一或多
  • er 关系线语义：-- 实线 = identifying（子实体依赖父实体存在）；.. 虚线 = non-identifying（两实体可独立）
  • gantt 任务行：任务名 : [标签...], [id], 开始, 结束或时长，标签必须写最前；四种标签 done/active/crit/milestone 可组合
  • gantt 时间格式：dateFormat 管输入解析格式，axisFormat 管坐标轴输出格式（strftime 风格）——一进一出别混
  • gitGraph：默认从 main 开始；branch X 创建即自动切换；merge 产生双圈 commit；方向 LR:/TB:/BT:（注意带冒号）
  • cherry-pick 三前提（易错）：id: 指向已存在且不在当前分支的 commit；当前分支需至少一个 commit；拣选 merge commit 必须给 parent:
  • 三层配置，优先级低到高：默认配置 → 站点级 mermaid.initialize({...}) → 图级 frontmatter config:（v10.5+ 推荐）/ directive %%{init: ...}%%（deprecated 仍可用）
  • 图级配置两种写法：frontmatter 用 YAML config: 键（推荐）；directive 是图定义前的 JSON %%{init}%%（deprecated 仍广泛可用，多个会合并、同键后者覆盖前者）
  • initialize 关键项：startOnLoad / theme / securityLevel / maxTextSize（默认 50000 熔断）/ maxEdges（默认 500）/ look: 'handDrawn'（v11 手绘）/ layout: 'elk'（v11 布局引擎）
  • 五个内置主题：default / neutral（打印友好）/ dark / forest / base（唯一可定制 themeVariables）；themeVariables 只认十六进制色值
  • securityLevel 四值：strict（默认，click callback 禁用）/ antiscript（留 HTML 剥 script）/ loose（全开，仅完全可信来源）/ sandbox（iframe 隔离，beta）
  • JS API（v10+ 全 async）：mermaid.run() 批量渲染 / mermaid.render(id, text) 返回 { svg, bindFunctions }（id 须全页唯一）/ mermaid.parse(text) 仅校验语法
  • mermaid-cli：包 @mermaid-js/mermaid-cli，命令 mmdc，底层 puppeteer 无头浏览器；-i in.mmd -o out.svg|png|pdf
  • 无障碍：所有图支持 accTitle: / accDescr:，渲染为 SVG <title>/<desc> + aria 属性
  • 原生渲染与集成：GitHub/GitLab/Gitea/Azure DevOps/Notion/Joplin/Obsidian/Typora 围栏直接出图；VitePress 需装 vitepress-plugin-mermaid、Slidev 内置
  • 图类型全表、形状/连线全表、三套箭头语义表、配置与安全表见下方各章节；易错点清单见本页收尾

一、图类型总览：22+ 种图速查 ​

核心图（有专属指南页）

图类型关键字一句话详见
流程图flowchart（旧 graph）方向 + 节点形状 + 连线 + 子图 + 样式流程图与时序图
时序图sequenceDiagram参与者 + 消息箭头 + 激活 + 控制块流程图与时序图
类图classDiagram成员/可见性 + 关系箭头八件套类图 / 状态图 / ER 图
状态图stateDiagram-v2起止 [*] + 复合状态 + fork/join/choice类图 / 状态图 / ER 图
ER 图erDiagram基数符号 + identifying 关系 + 属性块类图 / 状态图 / ER 图
甘特图gantt任务标签 + 依赖 + dateFormat/axisFormat甘特 / gitGraph / 更多图
饼图pieshowData 显示数值，最多两位小数甘特 / gitGraph / 更多图
Git 图gitGraphbranch/commit/merge/cherry-pick甘特 / gitGraph / 更多图

更多图类型（一句话速览）

图类型关键字一句话
思维导图mindmap缩进定层级，::icon() 加图标
时间线timeline时期 : 事件 : 事件，section 分段共享配色，实验态
象限图quadrantChartx-axis/y-axis/quadrant-1..4 标签，点坐标 0~1
桑基图sankey-betaCSV 三列「源,目标,数值」描述流量
XY 图xychart（旧 xychart-beta 也可）bar/line 可叠加，horizontal 横排
块图block-beta（新版 block 也可）columns n 网格 + 复用 flowchart 形状 + 块间连线
架构图architecture-betagroup/service/junction，边用 db:R --> L:server 式表达接口方位
报文图packet-betav11.7+ 可用 packet + 相对位 +16，位域如 0-15: "Source Port"
看板kanban列 + 缩进卡片，@{ ticket:, assigned:, priority: } 元数据
雷达图radar-betaaxis A, B, C + 曲线数据
用户旅程journey阶段 + 任务 + 满意度评分
需求图requirementDiagram需求元素 + 关系（satisfies/traces 等）
C4 架构C4Context（及 Container/Component/Dynamic）系统上下文/容器/组件分层架构图
另一种时序zenuml另一套时序图 DSL
树图treemap矩形嵌套面积图

-beta 后缀现状（detector 源码可见）：sankey / xychart / block / packet 已可省略；radar 仍仅接受 radar-beta。

二、flowchart：形状与连线速查 ​

节点形状（id + 包裹符号决定形状）：

形状语法备注
矩形[文本]默认形状
圆角矩形(文本)
体育场形([文本])stadium
子例程[[文本]]
圆柱/数据库[(文本)]
圆形((文本))
不对称旗帜>文本]
菱形/判断{文本}decision
六边形双大括号包裹文本写法见下方围栏示例
平行四边形[/文本/]
反平行四边形[\文本\]
梯形[/文本\]
反梯形[\文本/]
双圆(((文本)))
mermaid
flowchart LR
  A[矩形] --> B(圆角) --> C([体育场 stadium])
  D[[子例程]] --> E[(圆柱/数据库)] --> F((圆形))
  G>不对称旗帜] --> H{菱形/判断} --> I{{六边形}}
  J[/平行四边形/] --> K[\反平行四边形\]
  L[/梯形\] --> M[\反梯形/] --> N(((双圆)))

v11.3+ 起还有统一的 @{ shape: ... } 语法（30+ 形状，语义化命名 + 别名，如 diamond=decision/question、cyl=database/db），以及 @{ icon: "fa:bell" } 图标节点、@{ img: "url" } 图片节点。

连线全表：

语法含义
-->实线箭头
---实线无箭头
-.->虚线箭头（-.- 虚线无箭头）
==>粗线箭头
~~~隐形连线（只参与布局）
--o / --x圆头 / 叉头
<-->双向箭头
-->|文字| 或 -- 文字 -->带文字连线的两种写法
U --> V & W& 并联：一对多/多对多展开

其余速记：

  • 连线加长：多写 dash（--- < ---- < -----），拉长布局层级距离；边 ID 动画（v11.10+）：e1@A --> B 命名边，再 e1@{ animate: true }
  • subgraph 可嵌套、可 direction 设内部方向；坑：子图内节点与外部有连线时，该子图 direction 会被忽略、改随父图
  • 样式：classDef 定义类 → class A,B 类名 或 ::: 快捷附加；linkStyle n 按边定义顺序下标选边；外部 CSS 难覆盖内联样式
  • click 交互：click A href "url" "提示" _blank / click B callback；受 securityLevel 管控，strict 下 callback 禁用

三、箭头与基数符号语义表 ​

sequence 消息箭头：

语法含义
-> / -->实线 / 虚线，无箭头
->> / -->>实线 / 虚线，实心箭头（请求 / 响应惯用）
<<->> / <<-->>双向实线 / 虚线（v11.0+）
-x / --x实线 / 虚线带 ×（常表失败/丢失）
-) / --)实线 / 虚线开箭头（异步消息）

class 关系箭头八件套：

箭头语义记忆
<|--继承 Inheritance空心三角指父类
*--组合 Composition实心菱形在整体侧，部分不可独立存活
o--聚合 Aggregation空心菱形在整体侧，部分可独立
-->关联 Association实线箭头
--实线连接 Link无方向
..>依赖 Dependency虚线箭头
..|>实现 Realization虚线空心三角指接口
..虚线连接无方向

er 基数四对（符号靠近哪个实体，就说明该侧实体的数量）：

左侧右侧含义
|oo|零或一
||||恰好一
}oo{零或多
}||{一或多

读法示例：CUSTOMER ||--o{ ORDER : places = 一个 CUSTOMER 下单零或多个 ORDER，每个 ORDER 属于恰好一个 CUSTOMER；关系线本身也有语义——-- 实线 = identifying、.. 虚线 = non-identifying。

四、gantt 与 gitGraph 速查 ​

gantt 任务标签（必须写在任务行最前）：

标签含义
done已完成
active进行中
crit关键路径
milestone里程碑，渲染为单点（位置 = 开始时间 + 时长/2）

任务行格式：任务名 : [标签...], [id], 开始, 结束或时长。

gantt 时间与依赖指令：

指令作用
dateFormat定义输入日期格式（YYYY-MM-DD、X unix 等 token）
axisFormat定义坐标轴输出格式（strftime 风格，如 %m-%d）
tickInterval刻度密度：1day / 1week / 1month
excludes从时长计算剔除（weekends 或具体日期）
todayMarkeroff 隐藏今日线，或直接给样式
after id1 [id2...]依赖，多前置取最晚
until id持续到某任务开始

gitGraph commit 属性：

属性取值说明
id:自定义字符串供 merge/cherry-pick 引用
tag:自定义字符串打标签
type:NORMAL / REVERSE / HIGHLIGHT实心圆（默认）/ 叉圆（回滚）/ 高亮方块
  • 默认从 main 分支开始；branch X 创建即自动切换；checkout/switch 等价；merge 分支 产生双圈 merge commit；方向 LR:（默认）/ TB: / BT:（v11.0+，注意带冒号）；branch X order: n 控制泳道顺序
  • cherry-pick 三前提：id: 必填且指向已存在、不在当前分支的 commit；当前分支需至少一个 commit；拣选 merge commit 必须给 parent:
  • 专属 themeVariables：git0..git7 分支色（8 色循环）、gitBranchLabel0..7、commitLabelColor/Background/FontSize、tagLabelColor 等

五、配置与安全速查 ​

三层配置，优先级从低到高：默认配置 → 站点级 mermaid.initialize({...}) → 图级 frontmatter config:（v10.5+ 推荐）/ directive %%{init: ...}%%（deprecated 仍可用）。secure 数组内的键（securityLevel/startOnLoad/maxTextSize 等）只能由站点 owner 在 initialize 设置，图作者改不动。

js
mermaid.initialize({
  startOnLoad: true,
  theme: 'default',         // default | neutral | dark | forest | base
  securityLevel: 'strict',  // strict | loose | antiscript | sandbox
  maxTextSize: 50000,       // 超长图文本熔断
  maxEdges: 500,
  look: 'handDrawn',        // v11：手绘风（roughjs）
  layout: 'elk',            // v11：ELK 布局引擎
});

主题：default（默认）/ neutral（黑白打印友好）/ dark / forest / base（唯一可定制，配合 themeVariables）；themeVariables 只认十六进制色值，大量变量由 primaryColor 等基色派生。

securityLevel 四值：

值HTML 标签click 交互script说明
strict（默认）编码转义禁用（callback/js href 不生效）禁用最安全，默认值
antiscript允许启用剥离 script折中：留 HTML 去脚本
loose允许启用允许仅用于完全可信的图来源
sandbox允许受限禁用整图渲染进 sandbox iframe，JS 全禁；交互/链接受限，beta 品质

JS API（v10+ 全面 async）：

方法用途返回
mermaid.run({ querySelector | nodes, suppressErrors })批量渲染 DOM 中已有的图Promise<void>
mermaid.render(id, text)动态文本 → SVG 字符串，含 bindFunctionsPromise<{ svg, bindFunctions }>
mermaid.parse(text)仅校验语法，不渲染合法 Promise<{ diagramType }>，非法抛错

mermaid-cli：

bash
npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg          # 输出 svg/png/pdf
mmdc -i input.mmd -o output.png -t dark -b transparent

六、易错点清单 ​

  • end 小写坑：flowchart 节点或 sequence 控制块里全小写 end 会撞结束符——写 End/END 或加引号
  • o/x 开头节点坑：A---oB 被解析成圆头边、A---xB 成叉头边——加空格或用大写开头
  • %% 注释里别放花括号：会被误认成 directive 解析，图直接崩
  • themeVariables 不生效：忘了 theme: 'base'，或用了颜色名而非十六进制色值
  • 样式改不动：SVG 内联样式优先级高，外部 CSS 常覆盖失败——走 classDef / themeVariables / themeCSS
  • click 不响应：securityLevel 默认 strict 禁 callback；render API 场景还要手动调 bindFunctions(el)
  • mermaid.render 重复渲染报错：同 id 二次调用、组件热更新残留元素——每次生成唯一 id
  • SSR 崩溃：Node 端渲染因无 DOM 报错——VitePress/Nuxt 确保仅客户端执行（onMounted/<ClientOnly>/vitepress-plugin-mermaid），构建期出图走 mermaid-cli
  • gantt 标签顺序错：日期写在标签前会解析失败——元数据顺序须 tags → id → 起 → 止
  • cherry-pick 报错：忘写 id:、目标 commit 在当前分支、或拣选 merge commit 没给 parent:
  • 图文本超长熔断：默认 maxTextSize 50000 字符，超出报错；巨型 flowchart 还可能撞 maxEdges
  • directive/frontmatter 格式混淆：directive 是 JSON（键最好双引号），frontmatter 是 YAML（缩进、大小写敏感）
  • VitePress 默认不渲染：围栏 mermaid 只会被当代码高亮——需装 vitepress-plugin-mermaid；Slidev 内置

七、资源链接 ​