پرتوپرتو

نوار کناری (Sidebar)

یک نوار کناری قابل تنظیم برای ناوبری برنامه

معرفی

کامپوننت Sidebar یک نوار کناری پیشرفته برای ناوبری و سازماندهی محتوای برنامه است. این کامپوننت حالت‌های مختلف expanded و collapsed دارد.

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

  • برای اپلیکیشن‌هایی با ساختار ناوبری چندسطحی و عمیق
  • در داشبوردها و پنل‌های مدیریت
  • وقتی منوی ناوبری باید همیشه در دسترس باشد

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

  • برای application های بدون hierarchy — از NavigationMenu یا Tabs استفاده کنید
  • برای mobile-only navigation — از bottom navigation استفاده کنید

استفاده

برنامه من

منوی اصلی
نسخه 1.0.0
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from '@parto-system-design/ui'

export default function MyComponent() {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>
          <h2>برنامه من</h2>
        </SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>منوی اصلی</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton>داشبورد</SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton>پروژه‌ها</SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>
          <p>نسخه 1.0.0</p>
        </SidebarFooter>
      </Sidebar>
      <main>
        <SidebarTrigger />
        {/* محتوای اصلی */}
      </main>
    </SidebarProvider>
  )
}

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

Collapsible

<SidebarProvider>
  <Sidebar collapsible="icon">{/* محتوا */}</Sidebar>
</SidebarProvider>

موقعیت راست

<Sidebar side="right">{/* محتوا */}</Sidebar>

انواع Variant

{
  /* پیش‌فرض */
}
;<Sidebar variant="sidebar" />

{
  /* شناور */
}
;<Sidebar variant="floating" />

{
  /* داخلی */
}
;<Sidebar variant="inset" />

با آیکون و Tooltip

<SidebarMenuItem>
  <SidebarMenuButton tooltip="داشبورد">
    <Icons.home />
    <span>داشبورد</span>
  </SidebarMenuButton>
</SidebarMenuItem>

زیرمنو

<SidebarMenuItem>
  <SidebarMenuButton>پروژه‌ها</SidebarMenuButton>
  <SidebarMenuSub>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton>پروژه ۱</SidebarMenuSubButton>
    </SidebarMenuSubItem>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton>پروژه ۲</SidebarMenuSubButton>
    </SidebarMenuSubItem>
  </SidebarMenuSub>
</SidebarMenuItem>

با Badge

<SidebarMenuItem>
  <SidebarMenuButton>پیام‌ها</SidebarMenuButton>
  <SidebarMenuBadge>3</SidebarMenuBadge>
</SidebarMenuItem>

کنترل شده

const [open, setOpen] = useState(true)

;<SidebarProvider open={open} onOpenChange={setOpen}>
  <Sidebar />
</SidebarProvider>

Props

Prop

Type

SidebarProvider

Prop

Type

کامپوننت‌ها

  • Sidebar - wrapper اصلی
  • SidebarProvider - provider برای context
  • SidebarHeader - هدر سایدبار
  • SidebarContent - محتوای اصلی
  • SidebarFooter - فوتر سایدبار
  • SidebarGroup - گروه آیتم‌ها
  • SidebarGroupLabel - عنوان گروه
  • SidebarGroupContent - محتوای گروه
  • SidebarMenu - منوی سایدبار
  • SidebarMenuItem - آیتم منو
  • SidebarMenuButton - دکمه منو
  • SidebarMenuSub - زیرمنو
  • SidebarMenuSubItem - آیتم زیرمنو
  • SidebarMenuSubButton - دکمه زیرمنو
  • SidebarMenuBadge - نشان
  • SidebarTrigger - دکمه toggle
  • SidebarInset - محتوای اصلی صفحه

Hook

const { open, setOpen, state, isMobile, toggleSidebar } = useSidebar()

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

بکنید

  • از collapsible="icon" استفاده کنید تا کاربر بتواند sidebar را به حالت آیکون جمع کند - از tooltip روی SidebarMenuButton استفاده کنید تا در حالت جمع‌شده، نام آیتم نمایش داده شود - از SidebarMenuBadge برای نمایش تعداد اعلان‌ها یا آیتم‌های جدید استفاده کنید

نکنید

  • بیش از ۳ سطح زیرمنو نگذارید — ساختار را ساده نگه دارید - از Sidebar در صفحات عمومی بدون hierarchy استفاده نکنید — از NavigationMenu استفاده کنید

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

  • Responsive: در موبایل به sheet تبدیل می‌شود
  • با Cmd+B یا Ctrl+B سریع toggle می‌شود
  • وضعیت در cookie ذخیره می‌شود (پایدار بین session ها)
  • Tooltip در حالت collapsible="icon" نمایش داده می‌شود
  • سازگار با RTL

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

  • NavigationMenu — وقتی ناوبری افقی در هدر نیاز دارید، نه عمودی در کنار صفحه
  • AppBar — معمولاً در کنار Sidebar برای ساخت layout کامل داشبورد استفاده می‌شود
  • الگوی App Shell — راهنمای ترکیب Sidebar با سایر کامپوننت‌ها