PlantUML 布局指南：方向、间距与嵌套框

PlantUML 布局的最佳实践是描述结构，并为自动布局引擎提供少量有意义的约束。先确定整体方向，用语义容器组合相关元素，只在必要时调整间距，并将隐藏链接作为最后手段。

颜色和字体请参阅 PlantUML 颜色和主题指南。不同图表类型的示例请返回 PlantUML 示例中心。

要点总结

• 对于相关的图结构图表，top to bottom direction 是熟悉的默认方向；left to right direction 通常更适合横向流程。
• 嵌套的 package、node 和 rectangle 容器应表达所有权或部署边界。
• nodesep 和 ranksep 可以改善留白，但必须在目标渲染器中测试。
• 隐藏关系可以稳定困难的布局，但使用过多会让源代码变得脆弱。
• OnUML 没有布局引擎选择器；Smetana 等源代码 pragma 只有在配置的 PlantUML 渲染服务支持时才有效。

布局故障排查速查表

将代表性示例粘贴到 OnUML 编辑器，在提交布局约束前，对比源代码修改与渲染后的 PlantUML 预览。

开始之前

所需条件：

• 版本已知的 PlantUML 渲染器
• 关系已经正确的图表
• 横向和窄屏两种预览尺寸
• 大约 25 分钟
• 难度： 中级

不要一开始就尝试复刻幻灯片中的像素坐标。PlantUML 采用声明式设计，并使用自动布局。

第 1 步：选择主方向

完成这一步后，图表的主要阅读路径将与其使用场景相匹配。

@startuml
left to right direction

actor Customer
rectangle "Web Application" as Web
rectangle "Order Service" as Orders
database "Order Database" as DB

Customer --> Web
Web --> Orders
Orders --> DB
@enduml

将指令改为：

top to bottom direction

渲染两个版本。PlantUML 类图文档介绍了方向控制，并指出在该上下文中默认从上到下。选择交叉线最少且适合内容列宽的版本。

第 2 步：用有意义的框组合元素

完成这一步后，框将用于描述系统结构，而不只是推动节点改变位置。

@startuml
left to right direction

actor Customer

rectangle "Commerce Platform" {
  package "Ordering" {
    component "Checkout API" as Checkout
    component "Order Service" as Orders
  }

  package "Payments" {
    component "Payment Adapter" as Adapter
  }
}

node "External Provider" {
  component "Payment Gateway" as Gateway
}

Customer --> Checkout
Checkout --> Orders
Checkout --> Adapter
Adapter --> Gateway
@enduml

每个边界能够回答问题时，嵌套框才真正有效：哪个子系统拥有此组件，或它部署在哪里？部署图文档介绍了 node 等容器形式，其他图表类型还支持包和矩形。

请确认删除某个框时会丢失信息，而不只是改变位置。

第 3 步：谨慎调整间距

完成这一步后，标签和元素会有足够空间，又不会让图表尺寸过大。

@startuml
skinparam nodesep 45
skinparam ranksep 55
left to right direction

component Client
component API
component Worker
database Store

Client --> API : HTTPS
API --> Worker : queue
Worker --> Store : writes
@enduml

在兼容的图布局中，nodesep 影响节点之间的间距，ranksep 影响层级之间的间距。它们仍属于 skinparam 设置，因此需要使用实际图表类型和版本进行测试。skinparam 参考是官方起点。

每次只增加一个值。如果标签重叠，缩短标签或改变方向通常比设置极端间距更有效。

第 4 步：影响单条关系

完成这一步后，重要边将引导生成更易读的排列。

PlantUML 支持关系方向提示：

@startuml
class Checkout
class Order
class Payment
class Customer

Customer -down-> Checkout
Checkout -right-> Order
Checkout -left-> Payment
@enduml

应将提示视为自动布局中的偏好，而非保证坐标。只有在语义箭头仍然正确时才反转边，不要仅为了移动框而改变依赖含义。

第 5 步：将隐藏关系作为最后手段

完成这一步后，你会知道如何在不显示额外关系的情况下添加布局约束。

@startuml
left to right direction

component Web
component API
component Worker

Web --> API
API --> Worker
Web -[hidden]-> Worker
@enduml

隐藏边可以影响相对顺序，但也会引入未来编辑者必须理解的隐形知识。如果约束并不明显，请在图表源代码之外添加可见说明。相比一张由布局边组成的网，更应使用一条稳定的隐藏约束。

第 6 步：在 OnUML 中谨慎尝试 Smetana

完成这一步后，你会知道 OnUML 配置的 PlantUML 渲染服务是否接受 Smetana pragma，以及它能否改善当前图表。

OnUML 不提供 Graphviz/Smetana 选择器，也不能控制渲染器版本。PlantUML 通过源代码 pragma 提供 Smetana，你可以直接在图表中尝试：

@startuml
!pragma layout smetana

package Frontend {
  component Web
}
package Backend {
  component API
  database DB
}

Web --> API
API --> DB
@enduml

如果 OnUML 预览成功渲染，请对比使用和不使用 pragma 时的交叉线及容器尺寸。如果预览失败或稳定性变差，请删除它。布局引擎文档介绍了该 PlantUML 功能，但实际支持情况取决于 OnUML 配置的渲染服务。

第 7 步：保持源代码稳定

完成这一步后，未来修改导致意外布局变化的概率会降低。

请按以下顺序操作：

1. 按逻辑顺序声明元素。
2. 添加语义正确的关系。
3. 选择一个全局方向。
4. 添加有意义的容器。
5. 适度调整间距。
6. 最多添加少量关系提示。
7. OnUML 预览稳定后导出参考 SVG。

然后保存一份有代表性的 SVG 作为评审材料。源代码仍是权威内容；参考图片可以让意外变化更加明显。

应避免的常见错误

过早对抗自动布局。 先简化标签、删除意外环路并选择合适方向。

只把框当作定位工具。 容器应表达所有权、部署或其他真实边界。

添加大量隐藏链接。 模型变化后，隐形约束会相互影响且难以调试。

期望布局永远像素级一致。 渲染器变化可能影响顺序和间距。保持源代码简单；视觉稳定性重要时，比较导出的参考 SVG。

用布局解决样式问题。 拥挤的图表可能需要降低信息密度或明确层级，而不只是增大 ranksep。

成功标准

成功的布局具有清晰的阅读方向、很少的交叉边、有意义的嵌套边界，以及极少或没有隐形约束逻辑。它在读者实际浏览的页面宽度内也应易于理解。

常见问题解答

如何让 PlantUML 从左向右排列？

在图表开头附近添加 left to right direction。仍需检查结果，因为容器和关系也会影响自动布局。

如何在 PlantUML 中创建嵌套框？

根据图表类型嵌套 package、node 或 rectangle 等受支持容器。每个边界都应表达具体含义。

可以将 PlantUML 元素放在精确坐标吗？

PlantUML 的常规工作流是自动布局，而不是像素坐标。方向提示和约束可以影响结果，但不能提供通用的绝对定位画布。

应该使用 Graphviz 还是 Smetana？

OnUML 不提供引擎选择器。除非经过测试的 !pragma layout smetana 改善了当前预览，否则应保持默认设置；如果配置的渲染服务不支持该 pragma，请将其删除。

官方来源

• PlantUML 类图方向与关系
• PlantUML 部署图
• PlantUML 布局引擎
• PlantUML skinparam

先从结构入手，再添加最少量的有效布局约束。如果视觉层级仍然较弱，请使用 PlantUML 颜色和主题指南进行优化。如果真正的问题是关系过密，请用 PlantUML 类图指南简化模型；如果需要重新考虑图表类型，请使用 PlantUML 示例中心。