پرش به محتوای اصلی

راهنمای ویرایشگر نمودار Mermaid

زمان مطالعه: ۳ دقیقه

این ابزار چیست؟

Mermaid زبانی متنی برای کشیدن نمودار است. به‌جای چیدن جعبه و فلش با ماوس، ساختار را در چند خط می‌نویسید و چیدمان خودکار انجام می‌شود. این روش برای فلوچارت فرایندها، نمودار توالی درخواست‌ها، طراحی پایگاه داده و برنامه‌ریزی پروژه کاربرد دارد و چون نمودار فقط یک متن است، در گیت هم به‌راحتی نگه‌داری و مقایسه می‌شود.

این ابزار همه‌ی کار را در مرورگر شما انجام می‌دهد؛ کد نمودار به هیچ سرویسی فرستاده نمی‌شود. برچسب‌های فارسی با فونت وزیرمتن رسم می‌شوند و همین فونت داخل فایل‌های SVG و PNG هم می‌ماند، پس خروجی روی رایانه‌ی دیگران هم درست دیده می‌شود.

گام‌به‌گام

  1. یک الگو را بگذارید

    از فهرست «الگوی آماده» نمودار نزدیک به نیازتان را انتخاب کنید: فلوچارت، توالی، کلاس، ER، وضعیت، گانت، دایره‌ای، سفر کاربر، نقشه‌ی ذهنی یا خط زمان.

  2. کد را ویرایش کنید

    خط اول نوع نمودار است، مثل flowchart TD. پس از هر تغییر حدود نیم ثانیه صبر کنید تا پیش‌نمایش به‌روز شود.

  3. پیام خطا را بخوانید

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

  4. ظاهر را تنظیم کنید

    پوسته‌ی نمودار، پس‌زمینه‌ی شفاف و نمایش در اندازه‌ی واقعی را از نوار بالای ابزار انتخاب کنید.

  5. خروجی بگیرید

    SVG برداری است و برای چاپ و سند مناسب است؛ PNG برای پیام‌رسان و اسلاید. کیفیت PNG را تا چهار برابر اندازه‌ی اصلی می‌توانید بالا ببرید.

نمونه‌های کاربردی

  • فلوچارت ساده با برچسب فارسی

    سه مرحله‌ی پشت سر هم؛ پس از وارد کردن کد، نوع نمودار در زیر ویرایشگر نوشته می‌شود.

    flowchart LR
        A[ورود] --> B[بررسی] --> C[پایان]

    نتیجه: فلوچارت

  • گفت‌وگوی دو بخش در نمودار توالی

    پیام‌ها با فلش و دونقطه نوشته می‌شوند.

    sequenceDiagram
        کاربر->>سرور: درخواست ورود
        سرور-->>کاربر: ورود موفق

    نتیجه: توالی

  • نمودار دایره‌ای با پوسته‌ی خنثی

    مناسب چاپ سیاه‌وسفید؛ پوسته‌ی «خنثی» خودکار انتخاب می‌شود.

    pie showData
        title سهم فروش
        "حضوری" : 45
        "اینترنتی" : 55

    نتیجه: دایره‌ای

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

  • برچسبی که پرانتز، دونقطه یا نقل‌قول دارد را داخل نقل‌قول بگذارید، مثلاً A["پایان (موفق)"]؛ در غیر این صورت تحلیل‌گر آن را نمی‌فهمد.
  • نام گره را «end» با حروف کوچک نگذارید؛ این کلیدواژه است و فلوچارت را می‌شکند. از End یا نامی دیگر استفاده کنید.
  • نوع نمودار باید نخستین خط معنادار باشد. متن اضافه قبل از آن پیام «نوع نمودار شناخته نشد» می‌دهد.
  • گاهی خطایی که گزارش می‌شود نتیجه‌ی مشکلی در خط‌های قبلی است؛ اگر خط نشان‌داده‌شده درست به نظر می‌رسد، چند خط بالاتر را بررسی کنید.
  • نمودار با صدها گره کند و ناخوانا می‌شود. آن را به چند نمودار کوچک‌تر بشکنید.

کدام نوع نمودار را انتخاب کنم؟

برای نشان دادن مراحل و تصمیم‌ها از فلوچارت استفاده کنید. اگر مهم است چه کسی و در چه ترتیبی با چه کسی حرف می‌زند، نمودار توالی مناسب‌تر است. نمودار کلاس و نمودار ER برای مستندسازی ساختار برنامه و پایگاه داده‌اند و نمودار وضعیت رفتار یک سیستم را با حالت‌ها و گذارها شرح می‌دهد.

گانت برای زمان‌بندی کارها، دایره‌ای برای سهم هر بخش از کل، نقشه‌ی ذهنی برای مرور ایده‌ها و خط زمان برای رویدادهای تاریخی است. اگر داده‌ی عددی دارید که از جدول می‌آید، ابزار «نمودارساز از CSV» راحت‌تر است.

نوشتن فارسی در نمودار

متن فارسی را همان‌طور که هست در جعبه یا برچسب بنویسید؛ نیم‌فاصله و ارقام فارسی بدون مشکل کار می‌کنند. شناسه‌ی گره‌ها (مثل A و B) را کوتاه و لاتین نگه دارید و متن نمایشی را داخل براکت بگذارید تا کد خواناتر بماند.

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

پرسش‌های متداول

آیا کد نمودار من به سرور فرستاده می‌شود؟
خیر. موتور Mermaid روی همین سایت میزبانی می‌شود و نمودار کاملاً در مرورگر شما رسم می‌شود؛ هیچ درخواستی به سرویس بیرونی فرستاده نمی‌شود.
چطور برچسب فارسی بنویسم؟
متن فارسی را مستقیم در براکت یا نقل‌قول بنویسید، مثلاً A[شروع] یا A["متن با فاصله و (پرانتز)"]. اگر برچسب علامت خاص دارد، آن را داخل نقل‌قول بگذارید. فونت وزیرمتن در خروجی PNG و SVG هم گنجانده می‌شود.
چرا نمودار رسم نمی‌شود و خطا می‌بینم؟
معمولاً نوع نمودار در خط اول نوشته نشده یا یک فلش، براکت یا نقل‌قول ناقص مانده است. شماره‌ی خط مشکل‌دار و چند خط اطراف آن در جعبه‌ی خطا نشان داده می‌شود.

ابزارهای مرتبط