Подробное руководство по PlantUML: заголовок, шапка, подвал, примечание, подпись и легенда

В этом руководстве рассматриваются шесть наиболее часто используемыхтекстовых и аннотационныхэлементов в PlantUML. Во всех примерах я применяю внутренние соглашения:skinparam defaultFontSize 14иskinparam defaultFontColor #333333в начале файла.

Краткая ориентация по расположению каждого элемента относительно тела диаграммы:

Элемент	Позиция на отрисованном изображении	Многострочный блок?	Назначение
`title`	Верхний центр	Да (`end title`)	Название диаграммы / версия
`header`	Над диаграммой (шапка страницы)	Да (`endheader`)	Контекст, название организации, классификация
`footer`	Под диаграммой (подвал страницы)	Да (`endfooter`)	Автор, инструмент, метка времени
`подпись`	Непосредственно под диаграммой	Нет (одна строка)	Нумерация рисунков
`легенда`	Угол диаграммы	Да (`конец легенды`)	Ключ к символам / расшифровка
`примечание`	Присоединено к элементам или расположено рядом с ними	Оба варианта	Комментарий к конкретному элементу

1. Заголовок

Заголовок диаграммы расположен по центру в верхней части. Он поддерживает встроенную разметку (<размер>, <жирный>, <цвет>, <подчёркнутый>, <курсив>) и многострочную форму.

Простая форма:

title Обработка заказов

Многострочная форма с форматированием:

title
<size=20><b>Сервис обработки заказов</b></size>
<size=14><color=#555555>Контекстная диаграмма - v1.0</color></size>
endtitle

С использованием шаблона подзаголовка:В PlantUML нет специального ключевого слова для подзаголовка, поэтому его можно имитировать с помощью второй, более мелкой строки, как показано выше.

Распространённые ошибки

title без end title допустимо только для одной строки. Если вы напишете что-либо на следующей строке, PlantUML будет считать это частью заголовка только в том случае, если вы открыли блок с помощью end title.
Встроенные HTML-теги должны быть закрыты (<b>...</b>) или рендеринг будет непредсказуемым.
Заголовок является частью диаграммы, поэтому он отображается в экспорте — не дублируйте его в подписи имени файла.

2. Заголовок

Заголовок отображается над телом диаграммы, отделённый от него. Используйте его для организационного контекста, баннеров классификации или идентификаторов документов. Однострочная или блочная форма:

header Архитектурный совет - Внутренний

header
<font color=#777777 size=12>Архитектурный совет</font>
endheader

Когда использовать заголовок вместо title: title описывает что представляет собой диаграмма; header описывает контекст документа, к которому он относится (организация, конфиденциальность, выпуск). Их раздельное хранение позволяет наносить на множество диаграмм один и тот же заголовок.

3. Подвал

Подвал зеркально отражает заголовок в нижней части. Идеально подходит для указания авторства, инструментов и временных меток.

footer Подготовлено с помощью Visual Paradigm VPasCode

footer
<font color=#777777 size=11>Подготовлено с помощью Visual Paradigm VPasCode - Сгенерировано в 2025 году</font>
endfooter

Совет: PlantUML заменяет %date% (и %time%) в тексте заголовка/подвала/заголовка, что удобно для экспорта с штампом:

footer Отображено %date%

4. Подпись

Подпись подписи — это одна строка, размещённая непосредственно под диаграммой. Это естественное место для нумерации рисунков в документах (естественно сочетается с заголовка над ним).

caption Рисунок 1. Сервис заказов и его участники

В отличие от заголовка/заголовка/подвала, подписи занимает одну строку — без конец подписи блок не требуется и не ожидается. Делайте его кратким и в стиле ссылок.

5. Легенда

Легенда — это заключённая в рамку ключевая таблица, отображаемая в углу диаграммы. Она поддерживает форматированный текст и простой синтаксис таблиц (| | ячеек). Размещение управляется ключевым словом: верх, низ, лево, право, или центр.

легенда право
  |= Состояние |= Значение |
  | Новый | Создан, не оплачен |
  | Оплачен | Оплата зафиксирована |
  | Отправлен | Передан перевозчику |
конецлегенды

Варианты размещения

легенда верх лево
  Сплошная стрелка = синхронный вызов
  Пунктирная стрелка = асинхронное событие
конецлегенды

Когда использовать легенду вместо примечания: легенда расшифровывает обозначения, используемые на протяжении всей диаграммы (что означает символ, стиль линии или цвет). примечание содержит комментарий к одному конкретному элементу. Если читателю приходится искать значение символа в нескольких местах, преобразуйте его в легенду.

6. Примечание

Примечания прикрепляют комментарии к одному элементу или свободно перемещаются. Существует три стиля вызова.

Однострочное примечание, прикрепленное к элементу:

note top of Order : Однострочное свободно плавающее примечание

Многострочное примечание, прикрепленное к элементу:

note right of Order
  Многострочное примечание
  со свободным **форматированием**
end note

Отдельное (плавающее) примечание: присвойте ему псевдоним, чтобы впоследствии можно было установить ссылку или задать позицию.

note "Отдельное примечание, закреплённое через псевдоним" as N1

Ключевые слова для размещения прикрепляемых примечаний: top, bottom, left, right от <элемент>. В более новых версиях можно комбинировать два направления (например, note top left of), однако размещение в одном направлении является наиболее переносимым.

Ошибки

Форма в одну строку после : предназначена только для одной строки — используйте end note блок для нескольких строк.
Внутри end note блоки, стандартная встроенная разметка и даже встроенные диаграммы/поддиаграммы работают; избегайте незащищённых одиночных кавычек-- которые некоторые парсеры воспринимают как разделитель.

7. Объединение всех элементов

Приведённый ниже пример корректно проходит валидацию и демонстрирует все элементы в одной диаграмме. Примечания: заголовок/подвал/название/подпись обрамляют диаграмму снаружи внутрь, в то время как легенда и примечание находятся внутри холста диаграммы.

PlantUML

Редактировать PlantUML в VPasCode

PlantUML Edit PlantUML in VPasCode

@startuml
skinparam defaultFontSize 14
skinparam defaultFontColor #333333

header Architecture Review Board - Internal

title Order Processing Service - Context Diagram v1.0

caption Figure 1. Order service and its collaborators

footer Prepared using Visual Paradigm VPasCode

actor Customer
component WebApp
component OrderSvc
database OrderDB

Customer --> WebApp
WebApp --> OrderSvc
OrderSvc --> OrderDB

note right of OrderSvc
  Validates the order,
  then persists to OrderDB.
end note

legend right
  |= Arrow |= Meaning |
  | --> | Synchronous call |
  | ...> | Async event |
endlegend
@enduml

Edit PlantUML in VPasCode

Редактировать PlantUML в VPasCode

Документирование и рендеринг с помощью Visual Paradigm VPasCode

Вставьте любой из полных @startuml … @enduml файлы выше в Visual Paradigm VPasCode, и он отрендерит диаграмму, применит тему VP и позволит экспортировать её в PNG/SVG/PDF. Тема VP также может быть явно подключена в начале диаграммы:

!include https://static.visual-paradigm.com/web/resources/plantuml-stdlib/themes/vp.puml
skinparam vpDiagramType ComponentDiagram

Вы можете просматривать и рендерить их онлайн по адресу https://www.vpascode.com. Упорядочивайте свой шаблон последовательно — название и подпись для идентификации рисунка, заголовок/подвал для контекста документа, легенда для расшифровки обозначений, примечание для комментариев к каждому элементу — и ваши диаграммы будут выглядеть как связанный, профессионально изданный набор.

Эта статья также доступна на English, Español, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Việt Nam, 简体中文 and 繁體中文