نوار ناوبری (NavRail)
سایدبار دوگانه حرفهای با نوار آیکون و پنل ثانویه — الهامگرفته از Supabase
معرفی
کامپوننت NavRail یک سیستم ناوبری دوگانه است که شامل یک نوار آیکون باریک (Rail) و یک پنل ثانویه (Panel) میباشد. این الگو برای محصولات SaaS با صفحات و زیرمجموعههای متعدد طراحی شده است.
چه زمانی استفاده کنیم:
- محصولات با بخشهای متعدد و سابناوبری در هر بخش
- داشبوردهای تحلیلی با فیلترها و تنظیمات هر صفحه
- اپلیکیشنهایی که نیاز به دستهبندی سطح بالا و زیرمنوی متغیر دارند
چه زمانی استفاده نکنیم:
- اپلیکیشنهای ساده با کمتر از ۵ صفحه — از
Sidebarاستفاده کنید - صفحات بدون ساختار سلسلهمراتبی — از
NavigationMenuیاTabsاستفاده کنید - فقط موبایل — از bottom navigation استفاده کنید
محتوای صفحه
روی آیکونهای نوار کناری کلیک کنید تا پنلهای مختلف باز شوند.
استفاده
import {
NavRailProvider,
NavRail,
NavRailHeader,
NavRailFooter,
NavRailItem,
NavRailContent,
NavPanel,
NavPanelHeader,
NavPanelContent,
AppLayout,
AppLayoutContent,
NavRailTrigger,
} from '@parto-system-design/ui'
import { LayoutDashboard, Search, Settings } from 'lucide-react'
export default function MyApp() {
return (
<NavRailProvider defaultActiveItem="dashboard" defaultPanelOpen>
<AppLayout>
<NavRail>
<NavRailHeader>
<Logo />
</NavRailHeader>
<NavRailContent>
<NavRailItem itemId="dashboard" icon={<LayoutDashboard />} label="داشبورد" />
<NavRailItem itemId="search" icon={<Search />} label="جستجو" />
</NavRailContent>
<NavRailFooter>
<NavRailItem itemId="settings" icon={<Settings />} label="تنظیمات" />
</NavRailFooter>
</NavRail>
<NavPanel forItem="dashboard">
<NavPanelHeader title="داشبورد" />
<NavPanelContent>{/* سابناوبری داشبورد */}</NavPanelContent>
</NavPanel>
<NavPanel forItem="search">
<NavPanelHeader title="جستجو" />
<NavPanelContent>{/* فیلترهای جستجو */}</NavPanelContent>
</NavPanel>
<AppLayoutContent>{/* محتوای صفحه */}</AppLayoutContent>
</AppLayout>
</NavRailProvider>
)
}حالتها و انواع
حالت کنترلشده
برای کنترل state از بیرون (مثلاً وقتی routing مدیریت میشود):
const [activeItem, setActiveItem] = React.useState('dashboard')
const [panelOpen, setPanelOpen] = React.useState(true)
<NavRailProvider
activeItem={activeItem}
onActiveItemChange={setActiveItem}
panelOpen={panelOpen}
onPanelOpenChange={setPanelOpen}
>
{/* ... */}
</NavRailProvider>استفاده با Sidebar Primitives
داخل NavPanelContent میتوانید از کامپوننتهای Sidebar موجود استفاده کنید:
<NavPanel forItem="dashboard">
<NavPanelHeader title="داشبورد" />
<NavPanelContent>
<SidebarProvider defaultOpen>
<SidebarMenu>
<SidebarMenuItem>
<SidebarMenuButton isActive>نمای کلی</SidebarMenuButton>
</SidebarMenuItem>
<SidebarMenuItem>
<SidebarMenuButton>شاخصها</SidebarMenuButton>
</SidebarMenuItem>
</SidebarMenu>
</SidebarProvider>
</NavPanelContent>
</NavPanel>رفتار موبایل
در موبایل، Rail و Panel مخفی میشوند و با NavRailTrigger به صورت drawer باز میشوند:
<AppBar
logo={
<>
<NavRailTrigger />
<span>برنامه من</span>
</>
}
/>راهنمای استفاده
بکنید
- برای هر بخش اصلی یک
NavRailItemبا آیکون مشخص قرار دهید - محتوای Panel را متناسب با هر بخش تنظیم کنید (سابناوبری، فیلترها، جستجو) - ازNavRailSeparatorبرای گروهبندی بصری آیکونها استفاده کنید
نکنید
- بیش از ۸ آیکون در Rail قرار ندهید — اولویتبندی کنید - Panel را برای محتوای اصلی استفاده نکنید — فقط ناوبری و
فیلترها - آیکونهای بدون tooltip نگذارید —
labelبرای همه آیتمها الزامی است
جدول ویژگیها
NavRailProvider
| ویژگی | نوع | پیشفرض | توضیحات |
|---|---|---|---|
defaultActiveItem | string | null | null | آیتم فعال اولیه (uncontrolled) |
activeItem | string | null | — | آیتم فعال (controlled) |
onActiveItemChange | (id: string | null) => void | — | callback تغییر آیتم فعال |
defaultPanelOpen | boolean | false | وضعیت اولیه پنل (uncontrolled) |
panelOpen | boolean | — | وضعیت پنل (controlled) |
onPanelOpenChange | (open: boolean) => void | — | callback تغییر وضعیت پنل |
NavRail
| ویژگی | نوع | پیشفرض | توضیحات |
|---|---|---|---|
side | 'start' | 'end' | 'start' | موقعیت نوار (در RTL، start = سمت راست) |
NavRailItem
| ویژگی | نوع | پیشفرض | توضیحات |
|---|---|---|---|
itemId | string | — | شناسه یکتا (باید با forItem پنل مطابقت داشته باشد) |
icon | ReactNode | — | آیکون نمایشی |
label | string | — | متن tooltip و aria-label |
isActive | boolean | — | وضعیت فعال (خودکار از context، قابل override) |
asChild | boolean | false | استفاده از Slot برای عناصر سفارشی مثل Link |
NavPanel
| ویژگی | نوع | پیشفرض | توضیحات |
|---|---|---|---|
forItem | string | — | شناسه آیتم Rail مربوطه |
NavPanelHeader
| ویژگی | نوع | پیشفرض | توضیحات |
|---|---|---|---|
title | string | — | عنوان پنل |
showClose | boolean | true | نمایش دکمه بستن |
دسترسیپذیری
تعاملات کیبورد
| کلید | عملکرد |
|---|---|
Ctrl/Cmd + \ | باز/بسته کردن پنل |
Escape | بستن پنل |
Enter / Space | فعال کردن آیتم Rail |
ویژگیهای ARIA
- Rail:
role="navigation"باaria-label="ناوبری اصلی" - Panel:
role="complementary"باaria-hiddenدر حالت بسته - آیتم فعال:
aria-current="page" - هر آیتم:
aria-labelاز proplabel
کامپوننتهای مرتبط
- اگر فقط یک سایدبار ساده بدون Rail نیاز دارید ← Sidebar
- برای ناوبری افقی بالای صفحه ← AppBar
- برای ترکیب کامل AppShell با NavRail ← الگوی AppShell