Mermaid Kanban 图表语法详解：看板结构、任务元数据与 ticket 配置实战

Mermaid Kanban 图表语法详解：看板结构、任务元数据与 ticket 配置实战

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

Mermaid 的 Kanban（看板）图表用于以"列 + 卡片"的形式可视化任务在各类工作流阶段中的流转状态。本篇基于仓库官方文档 docs/syntax/kanban.md 展开，完整覆盖看板语法、任务元数据@{ ... }、ticketBaseUrl配置项与完整示例，并结合 kanban.jison 语法文件、kanbanDb.ts 与 kanbanRenderer.ts 等源码，说明每一处语法背后实际的解析、建模与渲染机制。读完本文，你可以直接编写带负责人、工单链接和优先级色条的看板图，并能定位其底层实现。

图的基本结构：kanban 关键字

Kanban 图表以kanban关键字开头，后接各列（阶段）定义，列下方以缩进方式挂载任务。最小可运行示例如下：

要点：

• 首行kanban声明图表类型（在 docs/syntax/kanban.md 的示例中，同时给出了mermaid-example与mermaid两种代码块形式）；
• column1是列的唯一标识符，[Column Title]是显示的列标题；
• task1[Task Description]必须缩进在所属列之下，缩进关系决定了任务归属哪一列。

定义列（Columns）

列代表工作流的不同阶段，例如 "Todo"、"In Progress"、"Done" 等。每一列通过"唯一标识符 + 方括号标题"定义：

columnId[Column Title]

• columnId：列的唯一标识符；
• [Column Title]：显示在列头部区域的标题，例如id1[Todo]。

源码视角：列其实是"第一层节点"

从 kanban.jison 的statement规则看，列和任务在语法层是同一种"node"语句：

| SPACELIST node shapeData { yy.addNode($1.length, $2.id, $2.descr, $2.type, $3); } | SPACELIST node { yy.addNode($1.length, $2.id, $2.descr, $2.type); }

关键在$1.length——语句前导空格（SPACELIST）的长度被当作节点的level（缩进层级）传入addNode。随后 kanbanDb.ts 中的getSection(level)逻辑（第 25-48 行）负责判定当前节点是"列"还是"任务"：

• 节点层级与第一个节点（即列层级）相同 → 视为列，推入sections数组；
• 层级更深 → 归属最近一列（parentId指向该列）；
• 若出现比列层级更浅、又不在 sections 中的节点，会抛出错误Items without section detected，这正是"任务必须缩进在列之下"这一文档约束的底层来源。

此外，nodeWithoutId规则（kanban.jison 第 146-149 行）说明列标题也可以不写显式 id：[In progress]这种写法会直接以描述文本作为 id，这在官方完整示例中确有使用（见下文）。

在列中添加任务（Tasks）

任务以缩进方式列在所属列下，同样采用"唯一标识符 + 方括号描述"的格式：

taskId[Task Description]

• taskId：任务的唯一标识符；
• [Task Description]：任务描述文本。

文档给出的示例：

docs[Create Documentation]

任务描述支持较长的多行文本（渲染时自动换行），例如完整示例中的Create renderer so that it works in all cases. We also add some extra text here for testing purposes...，这由 e2e/diagrams/kanban/4-should-handle-the-height-of-a-section-with-a-wrapping-node-at-the-end.mmd 等测试用例专门覆盖"换行卡片对列高影响"的场景。

为任务添加元数据（Metadata）

可以使用@{ ... }语法为每个任务附加元数据，元数据中可包含assigned（负责人）、ticket（工单号）、priority（优先级）等键值对，渲染时会附加显示在任务卡片上：

支持的元数据键

• assigned：指定任务负责人；
• ticket：将任务关联到某个工单或 issue 编号；
• priority：表示任务紧急程度，文档明确列出的允许取值为'Very High'、High'、Low'与'Very Low'。

源码视角：元数据按 YAML 解析

@{ ... }的识别在词法器中完成——kanban.jison 第 24-47 行 定义了SHAPE_DATA词元（含对双引号嵌套状态的处理），语法将拼接后的字符串作为shapeData传入addNode。在 kanbanDb.ts 的 addNode 中，shapeData被包成 YAML 对象后以yaml.JSON_SCHEMA解析，并逐字段提取：

• label：覆盖任务显示文本；
• icon：图标；
• assigned、ticket：转为字符串挂到节点上；
• priority：原样保留。

也就是说，@{ ... }内部实际是一份 YAML，键名区分大小写，值可以用引号包裹字符串。

优先级到颜色的映射

文档列出的四个优先级在渲染层被映射为卡片左侧的一条色带。查看 kanbanItem.ts 的 colorFromPriority 可以看到完整映射：

priority 值	渲染效果
Very High	红色色条（red）
High	橙色色条（orange）
Medium	无色条（null，源码额外支持的中间档）
Low	蓝色色条（blue）
Very Low	浅蓝色条（lightblue）

色条的绘制位于 kanbanItem.ts 第 137-152 行：在卡片矩形左侧x + 2处追加一条stroke-width: 4的竖线，上下端点按圆角半径rx内缩。可以看到源码还额外支持了文档未提及的Medium档位（渲染为无色条），从源码结构看这是为未来扩展预留的中间优先级。

配置项：ticketBaseUrl 与工单外链

可以通过在 Markdown 文件开头的配置块自定义 Kanban 图表。目前 Kanban 图表有一个配置项ticketBaseUrl，用于设置工单的基础 URL：

--- config: kanban: ticketBaseUrl: 'https://yourproject.atlassian.net/browse/#TICKET#' ---

工作机制：当某个任务带有ticket元数据时，图中的工单号会变成链接，指向外部工单系统。ticketBaseUrl提供基础 URL，其中的#TICKET#占位符会被任务元数据中的 ticket 值替换，从而拼出完整链接。该配置的 schema 定义可参考 config.schema.yaml 中的kanban段（ticketBaseUrl字段，第 1131 行附近）。

源码视角：链接如何被插入 SVG

在 kanbanItem.ts 第 43-53 行：

if ('ticket' in kanbanNode && kanbanNode.ticket && config?.kanban?.ticketBaseUrl) { ticketUrl = config?.kanban?.ticketBaseUrl.replace('#TICKET#', kanbanNode.ticket); link = shapeSvg .insert<SVGAElement>('svg:a', ':first-child') .attr('class', 'kanban-ticket-link') .attr('xlink:href', ticketUrl) .attr('target', '_blank'); }

三个条件缺一不可：节点有ticket字段、ticket 非空、配置了ticketBaseUrl。满足后，工单号文本会被包裹进<a>元素（类名kanban-ticket-link，target="_blank"新窗口打开），而assigned负责人则渲染在卡片右上角（见 第 77-105 行 的insertLabel与坐标偏移逻辑）。

渲染布局要点

kanbanRenderer.ts 的draw函数揭示了列与卡片的布局规则（第 46-89 行）：

• 每列宽度读取conf?.kanban?.sectionWidth，默认200；
• 列按顺序从左到右排布（section.x = WIDTH * cnt + ...），卡片宽度为列宽减去1.5 * padding，依次向下堆叠；
• 列高根据卡片总高动态计算，最小 50，并加上列标题占位高度；
• 若出现"列中再嵌套分组"，会直接抛出Groups within groups are not allowed in Kanban diagrams错误——看板图不支持两级以上分组。

完整示例

官方文档给出的完整看板示例（包含配置块、无 id 列、长文本卡片与全部元数据键）：

该示例覆盖了：无显式 id 的列（Todo、[In progress]）、同名字符串节点（两处[Create Documentation]与[Create Blog about the new diagram]）、超长换行卡片、assigned/ticket/priority三种元数据的单独与组合使用，以及ticketBaseUrl配置。仓库中与之对应的端到端测试数据位于 e2e/diagrams/kanban/，例如 10-full-example.mmd、7-should-handle-external-tickets.mmd、7-should-handle-prioritization.mmd 与 8-should-handle-assignments-prioritization-and-tickets-ids-in-the-same-item.mmd，分别验证换行列高、外部工单链接、优先级色条与三要素混合场景，可用作回归验证的参考样本。

编写要点小结

• 以kanban关键字起始；列用columnId[Column Title]定义，阶段名要唯一；
• 任务用taskId[Task Description]定义并缩进在所属列下，缩进层级决定归属，出现"无列任务"会被 kanbanDb.ts 直接报错拒绝；
• 可选元数据用@{ key: value, ... }附加，内部按 YAML 解析，支持assigned、ticket、priority（Very High/High/Low/Very Low，源码中另有Medium中间档）；
• 顶部 frontmatter 配置块中设置config.kanban.ticketBaseUrl并保留#TICKET#占位符，即可让工单号自动链接到外部工单系统；
• 优先级会渲染为卡片左侧色条：Very High 红、High 橙、Low 蓝、Very Low 浅蓝，见 kanbanItem.ts。

遵循"唯一标识符 + 正确缩进 + 元数据 + 配置项"这几条准则，即可用 Mermaid 构建出能映射真实项目工作流、并直连工单系统的完整看板图。本文所引文档源文件为 packages/mermaid/src/docs/syntax/kanban.md（站点文档 docs/syntax/kanban.md 为其自动生成的副本，请勿直接编辑）。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid