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

کپی و صفحه‌های باریک

کنترل‌های فعال همیشه در ردیفی ساده بالای محتوا دیده می‌شوند: ناحیهٔ هدف برای نشانگر دقیق 32px و برای لمس 44px است و با محتوا 8px فاصله دارد. بدون کنترل، فضایی رزرو نمی‌شود. هنگام کپی، فوکوس حفظ می‌شود و نوشتن تکراری تا پایان درخواست مسدود است. رد دسترسی یا نبود کلیپ‌بورد به‌صورت محلی در ::part(copy-status) با role="status" نمایش داده می‌شود و متن آن با label-copy-error قابل ترجمه است؛ تلاش دوباره از همان دکمه استفاده می‌کند. رویداد copied فقط پس از کپی موفق محتوای فعلی صادر می‌شود. تغییر منبع یا هدف کپی، بازخورد درخواست‌های قبلی را بی‌اعتبار می‌کند. با تغییر منبع، فوکوس دکمه حفظ می‌شود و منبع جدید را می‌توان بی‌درنگ کپی کرد.