مسیریاب (Breadcrumb)

معرفی

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

چه زمانی استفاده کنیم:

• وقتی سایت ساختار سلسله‌مراتبی دارد و کاربر در سطوح عمیق ناوبری قرار می‌گیرد
• در کنار PageHeader برای نمایش مسیر صفحه فعلی
• وقتی کاربر باید بتواند به سطوح بالاتر بازگردد

چه زمانی استفاده نکنیم:

• در navigation تک‌سطحی — وقتی همه صفحات هم‌عرض هستند breadcrumb معنا ندارد
• داخل modal یا drawer — breadcrumb برای navigation سطح صفحه است

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator } from '@partodata/ui'

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="#">خانه</BreadcrumbLink></BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem><BreadcrumbLink href="#">داشبورد</BreadcrumbLink></BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem><BreadcrumbPage>افکارسنجی</BreadcrumbPage></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

استفاده

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@partodata/ui'

export default function MyComponent() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">خانه</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/components">کامپوننت‌ها</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

حالت‌ها و انواع

جهت جداکننده

جداکنندهٔ پیش‌فرض (<BreadcrumbSeparator /> بدون children) از جهت خود فهرست پیروی می‌کند، نه جهت سند: dir روی BreadcrumbList (پیش‌فرض rtl) تعیین می‌کند که شورون به چپ باشد (راست‌به‌چپ) یا به راست (چپ‌به‌راست). پس یک مسیر انگلیسی داخل صفحهٔ فارسی کافی است dir="ltr" بگیرد.

<BreadcrumbList dir="ltr">
  <BreadcrumbItem>
    <BreadcrumbLink href="/">Home</BreadcrumbLink>
  </BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem>
    <BreadcrumbPage>Reports</BreadcrumbPage>
  </BreadcrumbItem>
</BreadcrumbList>

جداکننده سفارشی

جداکنندهٔ سفارشی بهتر است بی‌جهت باشد، مثل «/» یا «·»:

<BreadcrumbSeparator>/</BreadcrumbSeparator>

اگر آیکون جهت‌دار لازم است، هرگز یک شورون ثابت (Icons.chevronLeft) نگذارید؛ در یکی از دو جهت غلط است. جداکننده جهت فهرست را در data-direction (rtl یا ltr) دارد و آیکون با آن می‌چرخد:

<BreadcrumbSeparator>
  <Icons.arrowRight className="in-data-[direction=rtl]:rotate-180" />
</BreadcrumbSeparator>

استفاده از Dropdown

برای مسیرهای طولانی می‌توانید از dropdown استفاده کنید:

<BreadcrumbItem>
  <BreadcrumbEllipsis />
</BreadcrumbItem>

کامپوننت‌ها

• Breadcrumb — wrapper اصلی با nav و aria-label
• BreadcrumbList — لیست آیتم‌های مسیر
• BreadcrumbItem — هر آیتم مسیر
• BreadcrumbLink — لینک کلیک‌پذیر
• BreadcrumbPage — صفحه جاری (غیرقابل کلیک)
• BreadcrumbSeparator — جداکننده
• BreadcrumbEllipsis — نقاط برای مسیرهای طولانی

Props

BreadcrumbLink

راهنمای استفاده

دسترسی‌پذیری

• از nav با نام دسترس‌پذیر فارسی aria-label="مسیر ناوبری" استفاده می‌شود — این نام برای کاربر screen reader خوانده می‌شود، پس باید فارسی باشد. اگر صفحه‌ای غیرفارسی دارید، aria-label را روی Breadcrumb بازنویسی کنید
• متن مخصوص screen reader در BreadcrumbEllipsis نیز فارسی است («موارد بیشتر»)
• صفحه جاری با aria-current="page" مشخص می‌شود
• جداکننده با aria-hidden پنهان می‌شود
• سازگار با RTL

کامپوننت‌های مرتبط

• PageHeader — جای breadcrumb صفحه، prop breadcrumbs در PageHeader است تا مسیر ناوبری بالای عنوان صفحه نمایش داده شود؛ نوار بالای قاب محصول هیچ‌وقت breadcrumb یا عنوان صفحه ندارد