Kompleksowy przewodnik po PlantUML: Tytuł, Nagłówek, Stopka, Notatka, Podpis i Legenda

Ten przewodnik obejmuje sześć najczęściej używanych elementów tekstowych i anotacyjnych w PlantUML. W każdym przykładzie stosuję konwencje wewnętrzne: skinparam defaultFontSize 14 oraz skinparam defaultFontColor #333333 na początku pliku.

Szybkie wprowadzenie dotyczące lokalizacji każdego elementu względem ciała diagramu:

1. Tytuł

Tytuł diagramu znajduje się wyśrodkowany na górze. Obsługuje znaczniki wierszowe (<size>, <b>, <color>, <u>, <i>) oraz formę wieloliniową.

Prosta forma:

tytuł Usługa przetwarzania zamówień

Forma wieloliniowa z formatowaniem:

tytuł
<size=20><b>Usługa przetwarzania zamówień</b></size>
<size=14><color=#555555>Diagram kontekstowy - v1.0</color></size>
koniectytułu

Z wzorcem podtytułu: PlantUML nie posiada dedykowanego słowa kluczowego dla podtytułu, więc należy go zasymulować za pomocą drugiego, mniejszego wiersza, jak pokazano powyżej.

Typowe pułapki

• tytuł bez koniec tytułu jest w porządku tylko dla jednego wiersza. Jeśli wpiszesz cokolwiek w następnym wierszu, PlantUML potraktuje to jako część tytułu tylko wtedy, gdy otworzysz blok za pomocą koniec tytułu.

• Zagnieżdżone tagi HTML muszą być zamknięte (<b>...</b>) lub renderowanie będzie nieprzewidywalne.

• Tytuł jest częścią diagramu, więc pojawia się w eksportach — nie duplikuj go w podpisie nazwy pliku.

2. Nagłówek

Nagłówek renderuje się powyżej ciała diagramu, oddzielony od niego. Użyj go do kontekstu organizacyjnego, banerów klasyfikacyjnych lub identyfikatorów dokumentów. Wersja jedno-wierszowa lub blokowa:

nagłówek Architecture Review Board - Internal

nagłówek
<font color=#777777 size=12>Architecture Review Board</font>
koniec nagłówka

Kiedy używać nagłówka zamiast tytułu: tytuł opisuje czym jest diagram; nagłówek opisuje kontekst dokumentu, do którego należy (organizacja, poufność, wersja). Ich oddzielenie pozwala na stemplowanie wielu diagramów tym samym nagłówkiem.

3. Stopka

Stopka odbija nagłówek na dole. Idealna dla informacji o autorstwie, narzędziach i znacznikach czasu.

stopka Przygotowano za pomocą Visual Paradigm VPasCode

stopka
<font color=#777777 size=11>Przygotowano za pomocą Visual Paradigm VPasCode - Wygenerowano 2025</font>
koniecstopki

Wskazówka: PlantUML zastępuje %date% (oraz %time%) w tekście nagłówka/stopki/tytułu, co jest przydatne przy eksportach ze stemplem:

stopka Wyrenderowano %date%

4. Podpis

Podpis podpisu to pojedyncza linia umieszczona bezpośrednio poniżej diagramu. Jest to naturalne miejsce dla numeracji rysunków w dokumentach (naturalnie łączy się z tytułu powyżej).

podpis Rysunek 1. Usługa zamówień i jej współpracownicy

W przeciwieństwie do tytułu/nagłówka/stopki, podpisu przyjmuje jeden wiersz — nie koniec podpisu blok nie jest wymagany ani oczekiwany. Zachowaj go krótki i w stylu odwołań.

5. Legenda

Legenda to ramkowany klucz wyświetlany w rogu diagramu. Akceptuje bogaty tekst i prostą składnię tabeli (| | komórki). Umieszczenie jest kontrolowane przez słowo kluczowe: góra, dół, lewo, prawo, lub środek.

legend prawy
  |= Stan |= Znaczenie |
  | Nowy | Utworzony, niezapłacony |
  | Zapłacony | Płatność pobrana |
  | Wysłany | Przekazany przewoźnikowi |
endlegend

Opcje pozycjonowania

legend góra lewo
  Pełna strzałka = wywołanie synchroniczne
  Przerywana strzałka = zdarzenie asynchroniczne
endlegend

Kiedy używać legendy zamiast notatki: legenda wyjaśnia notację używaną w całym diagramie (co oznacza symbol, styl linii lub kolor). notatka komentuje jeden konkretny element. Jeśli czytelnik musi odszukać symbol w więcej niż jednym miejscu, promuj go do legendy.

6. Uwaga

Uwagi dołączają komentarz do pojedynczego elementu lub mogą być umieszczone swobodnie. Istnieją trzy style odwołań.

Jednowierszowa uwaga dołączona do elementu:

note top of Order : Jednowierszowa uwaga pływająca

Wielowierszowa uwaga dołączona do elementu:

note right of Order
  Wielowierszowa uwaga
  z dowolnym **formatowaniem**
end note

Uwaga samodzielna (pływająca): nadaj mu alias, aby później można było go powiązać lub umiejscowić.

note "Uwaga samodzielna zakotwiczona za pomocą aliasu" as N1

Słowa kluczowe dotyczące umieszczenia dla uwag dołączonych: góra, dół, lewo, prawo elementu <element>. W nowszych wersjach można łączyć dwa kierunki (np. note top left of), ale umieszczenie w jednym kierunku jest najbardziej przenośne.

Pułapki

• Forma jednowierszowa po : jest przeznaczona tylko dla jednego wiersza — użyj bloku end note dla wielu wierszy.

• Wewnątrz end note bloki, standardowe znaczniki inline, a nawet osadzone diagramy/poddiagramy działają; należy unikać niepotrzebnych, nieekranowanych znaków “”-- które niektóre parsery interpretują jako separator.

7. Połączenie wszystkich elementów

Poniższy kod poprawnie się waliduje i demonstruje wszystkie elementy w jednym diagramie. Uwagi: nagłówek/stopka/tytuł/podpis ramują diagram od zewnątrz do wewnątrz, podczas gdy legenda oraz notatka znajdują się wewnątrz płótna diagramu.

@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

Dokumentowanie i renderowanie za pomocą Visual Paradigm VPasCode

Wklej dowolny z pełnych @startuml … @enduml plików powyżej do Visual Paradigm VPasCode, a on wyrenderuje diagram, zastosuje motyw VP i umożliwi eksport do formatów PNG/SVG/PDF. Motyw VP można również jawnie dołączyć na początku diagramu:

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

Możesz przeglądać i renderować je online pod adresem https://www.vpascode.com. Uporządkuj swoje szablony spójnie — tytuł oraz podpis dla identyfikacji rysunku, nagłówek/stopka dla kontekstu dokumentu, legenda dla dekodowania notacji, uwaga dla komentarzy dotyczących każdego elementu — a Twoje diagramy będą czytać się jako spójny, profesjonalnie wydany zestaw.

Ten post dostępny jest również w English, Español, Français, Bahasa Indonesia, 日本語, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文