C4-PlantUML 主题系统详解：从使用到自定义

C4-PlantUML 主题系统详解：从使用到自定义

C4-PlantUML 项目地址: https://gitcode.com/gh_mirrors/c4p/C4-PlantUML

什么是 C4-PlantUML 主题

C4-PlantUML 主题系统是一套预定义的视觉样式集合，用于统一和美化使用 C4 模型绘制的架构图。与标准 PlantUML 主题类似，但专门针对 C4 模型的元素（如容器、组件、系统边界等）进行了优化设计。

主题使用指南

基础使用方法

要使用远程主题库中的主题（如 C4_united），只需在 PlantUML 文件中添加以下指令：

!theme C4_united from https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/themes

对于本地主题，使用类似语法但指向本地路径：

!theme C4_foo from /path/to/themes/folder

主题加载优先级

1. 默认主题（C4_blue）无需显式加载
2. 从远程仓库加载的主题
3. 从本地路径加载的主题
4. 从 C4 标准库加载的主题（PlantUML v1.2023.8+）

内置主题展示

C4-PlantUML 提供多种精心设计的内置主题，每种都有独特的视觉风格：

1. C4_blue（默认主题）

• 蓝色系专业风格
• 无需特别加载

2. C4_brown

• 大地色系
• 适合传统企业应用场景

3. C4_green

• 绿色环保风格
• 适合生态、环保相关系统

4. C4_sandstone

• 砂岩质感
• 中性色调，适合多种场景

5. C4_superhero

• 深色背景高对比度
• 适合演示场景

6. C4_united

• 基于 united 主题
• 现代扁平化设计

7. C4_violet

• 紫色系
• 适合创意类项目

扩展主题资源

Matt Weagle 开发了一系列基于 ColorBrewer 和 Seaborn 调色板的专业主题，这些主题提供了更丰富的色彩选择：

!theme cb_seq_YlOrBr_9 from https://raw.githubusercontent.com/mweagle/C4-PlantUML-Themes/main/palettes

这些主题特别适合：

• 需要特定配色方案的项目
• 数据密集型系统展示
• 学术和技术文档

自定义主题开发

主题文件结构

自定义主题文件应命名为 puml-theme-C4_[主题名].puml，包含两部分：

1. 标准 PlantUML 的 skinparam 和 style 定义
2. C4 特有的变量覆盖

关键可配置变量

基础样式

!$STEREOTYPE_FONT_SIZE ?= 12
!$TECHN_FONT_SIZE ?= 12
!$ELEMENT_FONT_COLOR ?= "#FFFFFF"

箭头样式

!$ARROW_COLOR ?= "#666666"
!$ARROW_FONT_COLOR ?= $ARROW_COLOR
!$ARROW_FONT_SIZE ?= 12

边界样式

!$BOUNDARY_COLOR ?= "#444444"
!$BOUNDARY_BG_COLOR ?= "transparent"
!$BOUNDARY_BORDER_STYLE ?= "dashed"

元素特定样式

每种 C4 元素都有对应的颜色变量，例如：

• 人员(Person)：$PERSON_BG_COLOR, $PERSON_BORDER_COLOR
• 系统(System)：$SYSTEM_BG_COLOR, $SYSTEM_BORDER_COLOR
• 容器(Container)：$CONTAINER_BG_COLOR, $CONTAINER_BORDER_COLOR

图例样式

!$LEGEND_TITLE_COLOR ?= "#000000"
!$LEGEND_FONT_COLOR ?= "#FFFFFF"
!$LEGEND_BG_COLOR ?= "transparent"

序列图主题支持

序列图的样式可以通过专门的 skinparam 配置：

skinparam SequenceLifelineBorderColor $ARROW_COLOR
skinparam SequenceGroupBodyBackgroundColor $SEQUENCE_BG_COLOR
skinparam SequenceGroupFontColor $BOUNDARY_COLOR

最佳实践建议

1. 保持一致性：在项目中统一使用同一主题
2. 考虑可读性：确保文字与背景有足够对比度
3. 语义化配色：使用颜色传达额外信息（如红色表示外部系统）
4. 版本控制：将自定义主题文件纳入版本管理
5. 文档记录：为主题使用编写简单说明

通过合理使用主题系统，可以显著提升架构图的可读性和专业性，同时保持整个项目文档的视觉一致性。

C4-PlantUML 项目地址: https://gitcode.com/gh_mirrors/c4p/C4-PlantUML