Mermaid

نمودارهای Mermaid (فلوچارت، توالی، کلاس، وضعیت، گانت…) را به‌شکل وب‌کامپوننتی مستقل از فریم‌ورک رندر می‌کند. <r-mermaid> کتابخانهٔ mermaid را در نخستین رندر به‌شکل تنبل بار می‌کند (برنامه‌هایی که هرگز از آن استفاده نمی‌کنند چیزی نمی‌پردازند) و نمودار را در shadow root خودش می‌کشد، پس از استایل‌های صفحه جدا می‌ماند.

کجا به کارش ببرید: وقتی می‌خواهید نموداری را که به‌شکل متن نوشته شده در هر صفحه‌ای بگذارید، بی‌آنکه خودتان mermaid را سیم‌کشی کنید — و در صورت نیاز با نوار رونوشت / دانلود / تمام‌صفحه و نمایشگرِ جابه‌جایی و بزرگ‌نمایی.

شروع سریع

graph LR; A[Request] --> B[Validate]; B --> C[Store]; C --> D[Respond]

<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> خالی یک نمودار ایستای تمیز است. نوار ابزار با نگه‌داشتن نشانگر (بالا سمت راست) پیدا می‌شود.

graph TD; A[Start] --> B[Do work]; B --> C[End]

<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 و منبع همیشه کار می‌کند.