Mermaid.js 看板语法与工作流指南

看板是一种可视化的工作流管理工具，用于跟踪不同处理阶段（如待办事项、进行中和已完成）的任务或工作项。Mermaid.js 将其作为原生功能引入，这种基于文本的方法使开发团队和项目管理人员能够快速在文档文件中创建交互式任务仪表板，而无需管理手动跟踪应用程序或第三方图像元素。

基本语法结构

每个看板都以 kanban 声明头开始。列通过使用 section 关键字定义，每个任务卡片通过使用缩进空格块按顺序列在各列下方。

Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
kanban
title "示例项目冲刺"
section 待办
  设计数据库模式
  撰写 API 路由
section 进行中
  实现认证中间件
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

语法参考

下表分解了在 Mermaid.js 中构建看板地图所使用的基础数据组件和参数。

语法组件 类型要求 描述与使用规则
声明 关键字标识符 初始化敏捷工作流块映射参数。必须使用确切的 kanban 块。
标题 引号字符串 一个可选的全局工作区标题，居中显示在看板画布的顶部。
章节列 关键字 + 名称 定义一个独立的工作流阶段列。使用 section 关键字，后接列的标签。
标准任务卡片 缩进字符串 一个表示单个卡片的纯文本描述。它必须直接在活动部分下方进行制表或缩进。
任务ID卡片 方括号标识符 一种使用显式唯一ID标记与显示标签并列的高级任务卡片跟踪格式：id[卡片文本].
元数据块 JSON配置映射 一个可选的属性块，使用以下语法规则附加：@{...}语法规则来分配属性，如工单优先级或负责人。

高级任务属性与元数据

对于详细的工程冲刺或缺陷跟踪工作流程，您可以直接将元数据属性分配到卡片上。通过将唯一的节点ID（如task1[...]）与尾随的JSON配置声明块（@{}），您可以在卡片元素的表面直接打印结构化变量，如任务指派者、优先级和内部跟踪工单。

支持的任务变量

属性键 值格式 视觉结果
assigned 引号内的字符串名称 直接在卡片详情矩阵中渲染分配的负责人或开发人员标签。
priority 引号内的等级字符串 显示任务严重程度基准（例如，'High', '中等', '低').
工单 整数或字母令牌 跟踪关联的开发任务编号或系统项目代码。

现实世界蓝图：敏捷开发发布冲刺

这个全面的蓝图用于跟踪基础设施部署发布。它规划了三个不同的列（待办事项、进行中和准备部署），并利用高级任务ID与结构化元数据参数相结合，为各个功能分配特定的开发人员和工单代码。

Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
kanban
title "Q3 核心功能发布看板"
section 待办事项
  task101[创建 API 端点文档]@{ assigned: 'Sarah K', priority: '中等' }
  task102[设计着陆页线框图]
section 进行中
  task201[优化数据库查询同步]@{ assigned: 'Alex M', priority: '高', ticket: 4012 }
  task202[配置 Lightbox UI 组件]@{ assigned: 'Sarah K', priority: '低' }
section 准备部署
  task301[实现多因素用户认证]@{ assigned: '开发团队', ticket: 3985 }
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

语法提示： 虽然简单的任务可以作为未加引号的纯文本行直接输入，但包含元参数的复杂任务 *必须* 使用唯一的 ID 映射字符串前缀（例如id1[...]@{...}）。在看板的不同部分重复使用完全相同的任务 ID 将覆盖属性或引发布局错误。

常见语法陷阱与系统限制

在设计高度密集、多阶段的布局系统时，请牢记以下结构化故障排除参数：

  • 卡片前必须有章节规则： 所有任务卡片必须位于活动列块之下。在主标题下方直接编写任务字符串行，而未先声明kanban标题，且未先声明一个section列标题，将导致编译停止。
  • 空白与缩进： 跟踪布局引擎根据行缩进制表符对卡片进行分组。请确保所有任务卡片行在它们对应的活动section标签下均匀缩进，以防止对齐中断。
  • 元数据分隔符格式： 在一个内部构建自定义属性时，@{ } 键和值必须映射到有效的系统参数。使用逗号分隔多个属性，并在字符串赋值时使用清晰的引号包围。
  • 卡片密度管理： 尽管Kanban组件完全响应式，但将单个看板挤满超过5列或添加数十行密集的元数据行会降低移动端的可扫描性。请有意识地平衡布局间距规则。
滚动至顶部