PlantUML 带有条件的动态图

PlantUML 动态时序图：变量与条件控制

PlantUML 支持通过变量和条件进行预处理，从而实现动态时序图。用户可以通过开关控制细节级别，在不创建多个静态图表的情况下显示或隐藏嵌套逻辑。

想象一下记录一个创建订单的 API 端点，它会触发数十个内部检查。完整的图表会变得臃肿，在多个静态版本间切换效率低下。

准备图表文本

基础图表文本通过添加变量和条件来增强。以下是一个示例：

participant Bob as b
participant Alice as a

!$aliceThoughts = "No"
!$bobThoughts = "No"

b -> a: Hi!

!if ($aliceThoughts == "Yes")
activate a
a->a: Oh my god, he messaged me!
a->a: What to do, what to say..
create participant Lisa as l
a -> l: Bob messaged me, what should I do?
activate l
l -> a: Just reply to him, gosh
deactivate l
!endif

a->b: Hi!
deactivate a

!if ($bobThoughts == "Yes")
activate b
b->b: She replied o_O
!endif

b->a: Uh... How are you?
deactivate b

变量 $aliceThoughts 和 $bobThoughts 控制代码块的可见性。PlantUML 预处理器在渲染时评估这些条件。

HTML 界面控制

开关通过 HTML 表单和 JavaScript 实现。用户选择细节级别，代码会动态更新图表文本并生成图像。

<form>
  <label for="aliceThoughts">显示 Alice 的内心想法：</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">不显示</option>
    <option value="yes">显示</option>
  </select>
</form>

<form>
  <label for="bobThoughts">显示 Bob 的内心想法：</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">不显示</option>
    <option value="yes">显示</option>
  </select>
</form>

JavaScript 监听下拉框变化，将值注入 PlantUML 模板，然后调用编码器生成 URL。

为 PlantUML API 编码文本

PlantUML 提供 HTTP API 进行渲染：https://www.plantuml.com/plantuml/png/<encoded_text>。支持 PNG 和 SVG 格式。

简单方法（Hex 编码）

将 UTF-8 文本转换为 hex 并添加 ~h 前缀：

function toHex(uml) {
  const umlFormatted = `@startuml\r\n${uml}\r\n@enduml`;
  const utf8 = unescape(encodeURIComponent(umlFormatted));
  var result = '';
  for (var i=0; i<utf8.length; i++) {
    result += utf8.charCodeAt(i).toString(16).padStart(2, '0');
  }
  return `https://www.plantuml.com/plantuml/png/~h${result}`;
}

适合短图表。限制：URL 长度（约 8KB）。

高级方法（Deflate + 自定义 Base64）

• Deflate 压缩。
• 使用 PlantUML base64 编码：0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_。

通过压缩处理大型图表。

function encodePlantUml(data) {
    const base64Map = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_';
    let result = '';
    for (let i = 0; i < data.length; i += 3) {
        const b1 = data[i];
        const b2 = i + 1 < data.length ? data[i + 1] : 0;
        const b3 = i + 2 < data.length ? data[i + 2] : 0;
        result += base64Map[b1 >> 2];
        result += base64Map[((b1 & 3) << 4) | (b2 >> 4)];
        result += base64Map[((b2 & 15) << 2) | (b3 >> 6)];
        result += base64Map[b3 & 63];
    }
    return result;
}

在 Confluence 中嵌入

通过 Confluence 宏插入 HTML+JS。无需后端依赖——渲染在浏览器中通过 PlantUML 公共服务器完成。企业环境可使用本地 PlantUML 服务器。

主要优势：

• 无需切换图表即可实现交互。
• 通过预处理处理复杂逻辑。
• 资源占用最小：HTML、JS、PlantUML API。
• 兼容 Confluence。

实现限制

• Hex 编码的 URL 长度限制。
• 依赖外部 PlantUML 服务器（可通过本地部署解决）。
• PlantUML 预处理器限制：不支持复杂计算，仅基本操作。

| 方法 | 最大文本大小 | 复杂度 |

|----------|---------------------|--------|

| Hex | ~2000 字符 | 低 |

| Deflate | ~50k+ 字符 | 高 |

关键要点

• PlantUML 预处理支持 !if 条件和变量，实现动态图表。
• HTML+JS 开关实时更新图表。
• PlantUML API 从编码 URL 生成 PNG，无需后端代码。
• 简单场景用 Hex，大型图表用 Deflate。
• 方案可在 Confluence 中运行，无 VPN 问题。

— Editorial Team