PlantUML 颜色和主题：实用样式指南

PlantUML 颜色可以帮助区分角色、边界和状态，又不至于让图表变成海报。最快的方法是先采用内置主题，再只添加图表真正需要的语义颜色。本指南通过可直接粘贴到渲染器中的示例演示这一工作流。

如果你仍在选择图表类型，请浏览 PlantUML 示例中心。下面的样式技巧特别适合身份验证流程；另请参阅 PlantUML 时序图指南。

要点总结

使用 !theme 建立协调一致的基础，再用局部颜色语法表达有意义的例外。

新建可复用样式时，优先使用类似 CSS 的 <style> 规则；PlantUML 已将 skinparam 标记为弃用，但仍为兼容性提供支持。

将颜色视为辅助信号。即使以灰度显示，标签、线型和形状仍应能够传达图表含义。

在图表实际使用的 PNG、SVG 或页面背景中测试对比度。

开始之前

所需条件：

PlantUML 渲染器或在线编辑器
一个已经能正确渲染的小型图表
使用产品或文档配色方案的权限
大约 20 分钟
难度： 初级

将样式与建模分开。先确保关系正确，再修改外观。PlantUML 的颜色文档支持命名颜色和十六进制值，主题文档则介绍可复用主题。

要将主题或配色方案与实际渲染输出进行比较，请打开 OnUML 编辑器，选择 PlantUML 模式，然后粘贴下方任一示例。

第 1 步：预览可用颜色

完成这一步后，你会得到由渲染器生成的颜色参考，而不是从其他地方复制的一份不可靠列表。

打开 OnUML 编辑器，选择 PlantUML 模式，粘贴以下源代码：

@startuml
colors
@enduml

要查找接近某种色调的颜色，请提供搜索词：

@startuml
colors chocolate
@enduml

输出结果就是验证依据：如果某个命名颜色出现在 OnUML 预览中，说明当前渲染器能够识别它。

第 2 步：为单个元素应用颜色

完成这一步后，颜色将用于表达业务含义，而非单纯装饰。

@startuml
actor Customer #DCEBFF
participant "Web App" as Web #E8F5E9
participant "Identity Service" as IdP #FFF3CD
database "User Store" as DB #F3E5F5

Customer -> Web: Submit credentials
Web -> IdP: Verify identity
IdP -> DB: Read account
DB --> IdP: Account record
IdP --> Web: Authentication result
Web --> Customer: Show signed-in state
@enduml

设计系统定义了精确色值时，十六进制值很有用；在小型示例中，命名颜色更易阅读。不要只用颜色表达成功、警告或失败：应保留明确的消息标签和参与者名称。

同样的技巧也适用于类图：

@startuml
class Order #E8F5E9
class Payment #FFF3CD
class PaymentFailure #FDECEC

Order --> Payment : requests
Payment ..> PaymentFailure : may create
@enduml

第 3 步：从内置主题开始

完成这一步后，字体、线条和表面将具备协调统一的基础样式。

@startuml
!theme spacelab

actor Customer
participant "Checkout API" as API
database Orders

Customer -> API: Place order
API -> Orders: Save order
Orders --> API: Order ID
API --> Customer: Confirmation
@enduml

在 OnUML 中运行这个辅助图表，可列出当前渲染器可用的主题：

@startuml
help themes
@enduml

官方主题库便于比较，但仍应在 OnUML 预览中验证所选主题。Web 编辑器无法访问 ./themes 等本地路径，因此请使用内置主题，或直接在 <style> 块中放置自定义规则。

第 4 步：创建可复用的类 CSS 样式

完成这一步后，源代码将为不同图表元素类型定义可复用规则。

@startuml
<style>
root {
  BackgroundColor #FFFFFF
  FontColor #172033
  LineColor #52627A
  FontName Inter
}
actor {
  BackgroundColor #DCEBFF
  LineColor #2457A7
}
participant {
  BackgroundColor #E8F5E9
  LineColor #2F6B3C
}
arrow {
  LineColor #52627A
  FontColor #172033
}
</style>

actor Customer
participant API
Customer -> API: Request
API --> Customer: Response
@enduml

PlantUML 在其样式文档中介绍了这套类 CSS 系统。不同图表类型和版本支持的具体选择器可能有所不同，因此在迁移大型样式库之前，请先渲染一个小型样例。

旧项目经常使用 skinparam：

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowColor #52627A
skinparam sequenceParticipantBackgroundColor #E8F5E9
Alice -> Bob: Compatible legacy styling
@enduml

skinparam 文档已将该机制标记为弃用，并建议转向类 CSS 样式。这并不意味着现有图表会停止工作，而是表示目标版本支持时，新的共享样式应优先采用 <style>。

第 5 步：构建无障碍配色方案

完成这一步后，即使颜色难以区分，图表仍然可以理解。

使用一组职责明确的小型配色方案：

角色	示例	附加信号
主要系统	`#DCEBFF`	实线边框
外部依赖	`#FFF3CD`	`<<external>>` 标签
成功	`#E8F5E9`	“Success” 文本
失败	`#FDECEC`	“Failure” 文本或虚线箭头

颜色页面说明，PlantUML 支持使用 #?light:dark 等形式自动选择前景色。它可以在两个候选色之间做选择，但不等于通过 WCAG 认证。请导出图表，在实际背景上测试对比度，并检查灰度效果。

第 6 步：在 OnUML 中保持样式可复用

完成这一步后，多张图表将共享一套可维护的视觉规则。

将共享的 <style> 规则保存在一段源代码片段中，以便粘贴到相关 OnUML 图表。修改片段后，先预览有代表性的时序图和类图，再将其应用到所有图表。与 Web 渲染器难以可靠复现的本地主题文件或持续变化的远程主题文件相比，应优先选择内置主题和内联样式。

对于间距、方向和容器，样式只能解决一半问题。请继续查看 PlantUML 布局指南。

应避免的常见错误

使用过多颜色。 大型配色方案会迫使读者先解读装饰，再理解含义。请将颜色限制在少数几个命名角色中。

覆盖主题的每一项属性。 如果绝大多数属性都被替换，主题就失去了价值。可以保留主题作为基础，也可以维护一份明确的样式文件。

将自动文本颜色当作无障碍测试。 它只是在候选色之间做选择，不会评估所有标签、边框和导出场景。

让样式掩盖模型错误。 再漂亮的箭头也可能表达错误依赖。请先评审语义，再处理呈现效果。

成功标准

样式成功的图表会在时序图和类图示例中使用相同的语义配色，即使以灰度显示仍清晰易读，并且只需更新主题或共享样式就能改变品牌呈现。即使没有颜色，标签仍能解释每种状态。

常见问题解答

PlantUML 可以使用十六进制颜色吗？

可以。PlantUML 的许多元素声明和样式属性都接受十六进制颜色。请在实际部署的图表类型和版本中测试具体语法。

PlantUML 主题是内置的吗？

PlantUML 提供内置主题，help themes 会列出当前 OnUML 渲染器可用的主题。

现在应该替换所有 `skinparam` 规则吗？

不一定。现有图表可以继续使用兼容规则，而新的共享样式可以逐步迁移到 <style>。请渐进迁移并对比渲染输出。

官方来源

PlantUML 颜色
PlantUML 主题
PlantUML 主题库
PlantUML 类 CSS 样式
PlantUML skinparam

现在你已经掌握一套可重复使用的样式工作流：选择基础主题、添加语义颜色、验证无障碍性，并集中管理可复用规则。使用 PlantUML 示例中心将这套系统应用到更多图表类型，再借助 PlantUML 布局指南优化构图。