Mermaid.js 块图语法与网格布局指南

块图是一种结构化布局引擎，用于表示复杂的软件架构、硬件平台或组织模型。Mermaid.js 原生引入了该引擎，块引擎将布局画布视为一个绝对的数学网格矩阵。这使得对列对齐、独立布局嵌套边界、结构间距块以及显式边缘端口连接配置具有精确控制。

理解网格矩阵策略

与动态猜测布局路径的标准自由形式流程图不同，块图基于一个刚性的线性坐标网格系统：

  • 列阈值：您可以通过使用列修饰符设置严格的水平上限。当网格被块填满时，额外的元素会自动整洁地换行到下一行。
  • 按网格字段调整大小：默认情况下，每个块占据一个单一的坐标单元格（$1 times 1$）。您可以通过为元素分配明确的列宽，使其完美地跨越多个轨道。

基本语法结构

每个布局都以块声明头开始。随后使用列关键字建立行宽容量，并在连续的行上声明块。

Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
块
  列 3
  componentA["第一个块"]
  componentB["中间块"]
  componentC["右侧块"]
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

语法参考

下表分解了块解释器原生识别的基础数据参数、自定义样式关键字和结构容器。

语法组件 类型要求 描述与视觉布局规则
声明 关键字标识符 初始化矩阵网格块画布。必须使用确切的块 头部字符串。
列集 关键字 + 整数 定义在换行前的总水平槽位数（例如，列 4).
标准块 ID + 可选标签 创建一个标准数据框：id["标签文本"]。形状装饰符匹配流程图语法（例如，(()) 用于圆形，[()] 用于数据库）。
块尺寸覆盖 冒号参数块 通过显式分配自定义列宽块，覆盖默认的 $1 times 1$ 布局比例网格足迹：id:宽度.
空间元素 保留关键字 使用确切的 space 关键字插入一个不可见的、结构性的 $1 times 1$ 空白间距块到当前行。你可以像 space:2.
块箭头 专用实体ID 在网格槽内渲染一个粗厚、结构化的过渡箭头框：arrowId<["标签"]>(方向)。方向包括上, 下, 左, 右.
复合包装器 块 / 结束容器 将一个独立的孤立子网格矩阵直接嵌套在父块槽内：block:子ID ... end。子块可以声明其自身的独立列限制。

高级功能：显式块尺寸与空间修饰符

对于非对称布局，您可以使用冒号分隔符，直接将显式的水平尺寸度量传递给标准块或空间分隔符（:宽度）。这会强制元素干净地跨越多个网格位置。

Mermaid


在VPasCode中编辑Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  列数 4
  wideComponent["宽仪表板标题"]:4
  leftBar["侧边栏"] space:2 rightBar["主面板"]
Edit Mermaid in VPasCode



在VPasCode中编辑Mermaid

高级功能：边类型、方向和连接选项

在块引擎内的连接分为标准语义线和结构布局块箭头。标准连接线支持指定显式的方向约束，以决定线条如何环绕元素。

1. 标准线连接器

块连接使用标准链接操作符（-->, --, <-->). 但是，您可以通过在括号内添加方向或修饰符来控制路由：

  • A --> B：从元素A到元素B绘制一条标准的方向线。
  • A -- x B：绘制一条连接路径，以“X”标记结束，表示路径被阻塞。
  • A -- o B：绘制一条连接路径，以开放的圆圈连接点结束。

2. 动态布局块箭头

块箭头被视为实际的布局组件，在您的行预算矩阵中占据实际的坐标索引块。它们使用大于号和小于号的语法属性来映射物理流程路径：

Mermaid


在VPasCode中编辑Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  columns 3
  producer["数据生产者"]
  midArrow<["转换流量"]>(right)
  consumer["数据消费者"]
Edit Mermaid in VPasCode



在VPasCode中编辑Mermaid

高级功能：子块矩阵嵌套（复合分组）

该block:id包装器作为一个独立的布局框上下文环境。应用程序组容器可以在子块内建立自己的独特水平列数，从而让复杂组件紧密分组，而不会影响全局父画布模板网格的间距。

Mermaid


在VPasCode中编辑Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  columns 2
  rootGateway["全局网关"]
  
  block:microserviceCluster
    columns 3
    auth["认证节点"]
    api["核心API"]
    worker["工作引擎"]
  end
Edit Mermaid in VPasCode



在VPasCode中编辑Mermaid

现实世界蓝图：带缓存的多层基础设施

这个全面的多行蓝图展示了清晰的生产级基础设施配置。它建立了一个三列的处理网格布局，使用结构化的空间元素来隔离数据库层，映射一条粗壮的向下块箭头，并使用嵌套的block:id ... end复合包装器。

Mermaid


在VPasCode中编辑Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  columns 3

  %% 第1行：入口服务
  dnsClient(("Web客户端"))
  loadBalancer["边缘负载均衡器"]
  space

  %% 第2行：向下连接到微服务的流程
  space
  downRoute<["转发流量"]>(down)
  space

  %% 第3行：复合应用环境集群
  block:appCluster
    columns 2
    authService["认证"]
    apiEngine["核心API工作器"]
  end
  space
  database[("PostgreSQL数据库")]

  %% 建立清晰的矩阵到矩阵的结构对齐
  loadBalancer --> appCluster
  appCluster --> database
Edit Mermaid in VPasCode



在VPasCode中编辑Mermaid

常见语法陷阱与系统限制

在编译精确的网格矩阵图时，请牢记以下验证检查，以防止解析错误：

  • 列预算强制执行：请仔细跟踪你的列数。如果你指定columns 3并且在一行中写入4个连续的块，第四个块将自动降为第二行，这可能会破坏预期的从左到右的连接路径。
  • 复合嵌套顺序：在使用block:id构建内部容器时，你必须始终使用end关键字在单独的一行上封闭子网格工作区，然后再声明后续元素。未能关闭块将停止图表构建。
  • 块箭头目标限制：括号中包含的方向属性（例如，(up), (down)）必须是完全匹配系统关键字的小写字面量。将方向大写会导致处理错误。
  • 标签边界碰撞：标准流程图形状装饰符（如圆括号()用于圆框或花括号{} 对于钻石）完全受支持。请确保形状内的所有显示文本标签使用干净的双引号，以避免字符被截断。
滚动至顶部