راهنمای جامع PlantUML: عنوان، سربرگ، پابرگ، یادداشت، زیرنویس و راهنما

این راهنما شش مورد از پرکاربردترین عناصر متنی و توضیحی را در PlantUML پوشش می‌دهد. در تمام مثال‌ها از قراردادهای داخلی من استفاده می‌کنم: skinparam defaultFontSize 14 و skinparam defaultFontColor #333333 در بالای فایل.

راهنمای سریع برای محل قرارگیری هر عنصر نسبت به بدنه نمودار:

۱. عنوان

عنوان نمودار در بالای آن به صورت وسط‌چین قرار می‌گیرد. از نشانه‌گذاری درون‌خطی پشتیبانی می‌کند (<اندازه>, <b>, <رنگ>, <u>, <i>) و یک شکل چندخطی.

شکل ساده:

عنوان: سرویس پردازش سفارش

شکل چندخطی با قالب‌بندی:

عنوان
<size=20><b>خدمات پردازش سفارش</b></size>
<size=14><color=#555555>نمودار زمینه - نسخه ۱.۰</color></size>
پایان‌عنوان

با الگوی زیرعنوان: PlantUML هیچ کلمه کلیدی اختصاصی برای زیرعنوان ندارد، بنابراین آن را با یک خط دوم کوچک‌تر شبیه‌سازی کنید، همان‌طور که در بالا نشان داده شد.

اشتباهات رایج

• عنوان بدون پایان‌عنوان مناسب است فقط برای یک خط. اگر چیزی در خط بعد بنویسید، PlantUML آن را بخشی از عنوان در نظر خواهد گرفت، تنها اگر بلوکی را با پایان‌عنوان.

• برچسب‌های HTML درون‌خطی باید بسته شوند (<b>...</b>) یا نمایش غیرقابل پیش‌بینی خواهد بود.

• عنوان بخشی از نمودار است، بنابراین در خروجی‌ها ظاهر می‌شود — آن را در عنوان نام فایل تکرار نکنید.

۲. سربرگ

سربرگ در بالایبدنه نمودار، جدا از آن، نمایش داده می‌شود. از آن برای زمینه سازمانی، بنرهای طبقه‌بندی یا شناسه‌های سند استفاده کنید. به صورت تک‌خطی یا بلوکی:

سربرگ شورای بررسی معماری - داخلی

سربرگ
<font color=#777777 size=12>شورای بررسی معماری</font>
پایان‌سربرگ

چه زمانی از سربرگ در مقابل عنوان استفاده کنیم: عنوان عنوانتوضیح می‌دهد که نمودار چیست; سربرگ سربرگتوضیح می‌دهد که زمینه‌ای که سند به آن تعلق دارد (سازمان، محرمانگی، انتشار). جدا نگه داشتن آن‌ها به شما اجازه می‌دهد تا بسیاری از نمودارها را با همان سربرگ مهر کنید.

۳. پاورقی

پاورقی در پایین، بازتابی از سربرگ است. ایده‌آل برای ذکر نام نویسنده، ابزار و زمان‌مهر.

footer Prepared using Visual Paradigm VPasCode

footer
<font color=#777777 size=11>Prepared using Visual Paradigm VPasCode - Generated 2025</font>
endfooter

نکته: PlantUML جایگزین‌های %date% (و %time%) را درون متن سربرگ/پاورقی/عنوان جایگزین می‌کند که برای صادرات مهرشده کاربردی است:

footer Rendered %date%

۴. زیرنویس

یک زیرنویس یک خط تکی است که مستقیماً در زیر نمودار قرار می‌گیرد. این مکان رایج برای شماره‌گذاری شکل‌ها در اسناد است (به‌طور طبیعی با یک عنوان در بالا جفت می‌شود).

caption Figure 1. Order service and its collaborators

برخلاف عنوان/سربرگ/پاورقی, زیرنویس یک خط را می‌گیرد — بدون پایان توضیح بلوک مورد نیاز یا انتظار است. آن را کوتاه و به سبک ارجاع نگه دارید.

۵. راهنما

راهنما یک کلید مربعی است که در گوشه‌ای از نمودار نمایش داده می‌شود. این راهنما از متن غنی و نحو جدول ساده (پذیرش می‌کند.| | سلول‌ها). محل‌گذاری با یک کلمه کلیدی کنترل می‌شود: بالا, پایین, چپ, راست، یا مرکز.

راهنمای راست
  |= وضعیت |= معنا |
  | جدید | ایجاد شده، پرداخت نشده |
  | پرداخت شده | پرداخت ثبت شده |
  | ارسال شده | تحویل به حمل‌کننده |
پایان راهنما

گزینه‌های موقعیت‌دهی

راهنمای بالا-چپ
  فلش توپر = فراخوانی همگام
  فلش خط‌چین = رویداد ناهمگام
پایان راهنما

چه زمانی از راهنما به جای یادداشت استفاده کنیم: یک راهنما نشانه‌های استفاده‌شده را رمزگشایی می‌کند در سراسر نمودار (معنای یک نماد، سبک خط یا رنگ را توضیح می‌دهد). یک یادداشت درباره یک عنصر خاصاگر خواننده شما باید نمادی را در بیش از یک مکان جستجو کند، آن را به راهنما ارتقا دهید.

۶. یادداشت

یادداشت‌ها توضیحات را به یک عنصر واحد پیوند می‌دهند یا به‌صورت آزاد شناور می‌شوند. سه سبک فراخوانی وجود دارد.

یادداشت تک‌خطی پیوند‌شده به یک عنصر:

note top of Order : یادداشت شناور تک‌خطی

یادداشت چندخطی پیوند‌شده به یک عنصر:

note right of Order
  یادداشت چندخطی
  با **فرمت‌بندی** آزاد
end note

یادداشت مستقل (شناور): به آن یک نام مستعار بدهید تا بعداً بتوان آن را پیوند داد یا موقعیت‌دهی کرد.

note "یادداشت مستقل پیوند‌شده از طریق نام مستعار" as N1

کلیدواژه‌های مکان‌گذاری برای یادداشت‌های پیوند‌شده: بالا, پایین, چپ, راست از <عنصر>. در نسخه‌های جدیدتر می‌توانید دو جهت را ترکیب کنید (مثلاً note top left of)، اما مکان‌گذاری تک‌جهتی قابل‌حمل‌ترین است.

نکات احتیاطی

• فرم تک‌خطی پس از : فقط برای تک‌خط است — از end note برای چند خط استفاده کنید.

• داخل end note بلوک‌ها، نشانه‌گذاری خطی استاندارد و حتی نمودارها/زیرنمودارهای تعبیه‌شده کار می‌کنند؛ از علائم نقل‌قول بدون فرار (unescaped) که به تنهایی باقی مانده‌اند، پرهیز کنید.-- که برخی پردازنده‌ها آن را به عنوان جداکننده تفسیر می‌کنند.

۷. گردآوری همه اجزا

متن زیر به‌طور تمیز اعتبارسنجی می‌شود و تمام عناصر را در یک نمودار نمایش می‌دهد. یادداشت‌ها: سربرگ/پابرگ/عنوان/زیرنویس نمودار را از بیرون به داخل قاب‌بندی می‌کنند، در حالی که راهنما و یادداشت درون بوم نمودار قرار می‌گیرند.

@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

مستندسازی و رندرینگ با Visual Paradigm VPasCode

هر یک از موارد کامل زیر را در 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قالب‌های پایه (boilerplate) خود را به‌صورت یکسان و منظم مرتب کنید — عنوان و زیرنویس برای شناسایی شکل، سربرگ/پابرگ برای زمینه سند، راهنما برای تفسیر نمادها، یادداشت برای توضیحات تک‌تک عناصر — و نمودارهای شما مانند مجموعه‌ای منسجم و به‌صورت حرفه‌ای منتشرشده به‌نظر خواهند رسید.

This post is also available in Deutsch, English, Español, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文.