Mermaid
نمودارهای Mermaid (فلوچارت، توالی، کلاس، وضعیت، گانت…) را بهشکل وبکامپوننتی مستقل از فریمورک رندر میکند. <r-mermaid> کتابخانهٔ mermaid را در نخستین رندر بهشکل تنبل بار میکند (برنامههایی که هرگز از آن استفاده نمیکنند چیزی نمیپردازند) و نمودار را در shadow root خودش میکشد، پس از استایلهای صفحه جدا میماند.
کجا به کارش ببرید: وقتی میخواهید نموداری را که بهشکل متن نوشته شده در هر صفحهای بگذارید، بیآنکه خودتان mermaid را سیمکشی کنید — و در صورت نیاز با نوار رونوشت / دانلود / تمامصفحه و نمایشگرِ جابهجایی و بزرگنمایی.
شروع سریع
<r-mermaid>graph LR; A[Request] --> B[Validate]; B --> C[Store]</r-mermaid>import 'ranui'; // یا نقطهٔ ورود مستقل:
import 'ranui/mermaid';منبع نمودار از محتوای متنی عنصر خوانده میشود، یا از ویژگی code که بهشکل URI کدگذاری شده است (وقتی نحو شامل < است — مثلاً <|-- در classDiagram — از code استفاده کنید تا از تجزیهٔ HTML جان سالم به در ببرد):
el.code = 'classDiagram\n Dog --|> Animal'; // ستِرِ خصیصه، خودش URI را کدگذاری میکندکنترلها
هر کنترل با یک ویژگی بولی بهخواست خودتان روشن میشود؛ <r-mermaid> خالی یک نمودار ایستای تمیز است. نوار ابزار با نگهداشتن نشانگر (بالا سمت راست) پیدا میشود.
<r-mermaid copy download fullscreen>graph TD; A --> B; B --> C</r-mermaid>- copy: منبع نمودار را در تختهگیره رونوشت میکند.
- download: SVG / PNG / منبع (
.mmd)؛ اگر یک قالب باشد مستقیم دانلود میشود و اگر چند تا باشد منویی نشان میدهد. باdownload="svg"یاdownload="svg png"محدودش کنید. - fullscreen: جعبهٔ نوری بدون سربرگ (r-modal) را با جابهجایی و بزرگنمایی باز میکند (چرخ ماوس برای بزرگنمایی، کشیدن برای جابهجایی، و بازنشانی)؛ بستن با ✕، کلیک روی پسزمینه، یا
Esc.
مرجع API
ویژگیها
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
code | string (کدگذاریشدهٔ URI) | — | منبع نمودار. نبودِ آن به محتوای متنی عنصر برمیگردد. |
theme | 'auto' | 'light' | 'dark' | 'auto' | پوستهٔ mermaid. auto از صفحه پیروی میکند (.dark / [data-ran-theme]) و هنگام تعویض دوباره رندر میکند. |
copy | بولی | خاموش | دکمهٔ رونوشت منبع را نشان میدهد. |
download | بولی / "svg png source" | خاموش | دکمهٔ دانلود را نشان میدهد؛ مقدار، قالبهای پیشنهادی را محدود میکند. |
fullscreen | بولی | خاموش | دکمهٔ تمامصفحه را نشان میدهد. |
sheet | string | — | CSS اضافی که به shadow root تزریق میشود. |
label-* | string | انگلیسی | بازنویسی برچسب کنترلها: label-copy، label-download، label-fullscreen، label-zoom-in، label-zoom-out، label-reset، label-diagram (نام پنجرهٔ تمامصفحه). |
رویدادها
همهٔ رویدادها حباب میکنند و از مرز shadow میگذرند (composed).
| رویداد | detail | چه زمانی |
|---|---|---|
render | { ok: true } | رندر یک نمودار تمام شد |
copied | { kind: 'source' } | منبع رونوشت شد |
download | { format: 'svg' | 'png' | 'source' } | فایلی دانلود شد |
error | { message: string } | تجزیه یا رندر نمودار شکست خورد |
fullscreenchange | { open: boolean } | جعبهٔ نوری تمامصفحه باز یا بسته شد |
Partهای CSS
| Part | توضیح |
|---|---|
mermaid | پوشش بیرونی. |
diagram | نگهدارندهٔ نمودار رندرشده. |
toolbar | نوار کنترل که با نگهداشتن نشانگر میآید. |
button | هر دکمهٔ آیکون در نوار. |
error | جعبهٔ پیام خطا (هنگام شکست رندر). |
r-mermaid::part(toolbar) {
background: var(--surface);
}متغیرهای CSS
روی خود عنصر بازنویسی کنید (هرکدام نخست به یک توکن معنایی و سپس به مقداری عینی برمیگردند): --ran-mermaid-padding، --ran-mermaid-toolbar-background، --ran-mermaid-toolbar-gap، --ran-mermaid-button-size، --ran-mermaid-button-color، --ran-mermaid-button-hover-background، --ran-mermaid-error-color.
یادداشتها
- بارگذاری تنبل: mermaid (و r-modal که برای تمامصفحه به کار میرود) import پویا هستند، پس تنها هنگام رندر یک نمودار یا باز شدن تمامصفحه، بهشکل تکههای ناهمگام جداگانه میرسند.
- وفاداری رندر:
<r-mermaid>از رندر خودِ mermaid استفاده میکند، پس همهٔ گونههای نمودار و همهٔ پوستهها پشتیبانی میشوند. - خروجی PNG: نمودارهایی که برچسب HTML دارند (
htmlLabelsدر mermaid) از راه<foreignObject>ترسیم میشوند و این میتواند canvas را آلوده کند و خروجی PNG را شکست دهد؛ در آن حالت رویدادerrorارسال میشود. خروجی SVG و منبع همیشه کار میکند.