نوار منو (Menubar)

نوار منوی افقی با چند منوی کشویی برای رابط کاربری شبیه برنامه‌های دسکتاپ

نصب (Installation)

1npx @quark-lab/rad-ui add menubar

نمونه‌ها (Examples)

استفاده پایه (Basic)

نوار منوی ساده با چند منوی کشویی

مشاهده کد
1import {
2  Menubar,
3  MenubarContent,
4  MenubarGroup,
5  MenubarItem,
6  MenubarMenu,
7  MenubarSeparator,
8  MenubarTrigger,
9} from "@/components/ui/menubar";
10
11export default function BasicExample() {
12  return (
13    <Menubar className="w-72">
14      <MenubarMenu>
15        <MenubarTrigger>فایل</MenubarTrigger>
16        <MenubarContent>
17          <MenubarGroup>
18            <MenubarItem>تب جدید</MenubarItem>
19            <MenubarItem>پنجره جدید</MenubarItem>
20          </MenubarGroup>
21          <MenubarSeparator />
22          <MenubarGroup>
23            <MenubarItem>اشتراک</MenubarItem>
24            <MenubarItem>چاپ</MenubarItem>
25          </MenubarGroup>
26        </MenubarContent>
27      </MenubarMenu>
28      <MenubarMenu>
29        <MenubarTrigger>ویرایش</MenubarTrigger>
30        <MenubarContent>
31          <MenubarGroup>
32            <MenubarItem>پروفایل</MenubarItem>
33            <MenubarItem>صورتحساب</MenubarItem>
34          </MenubarGroup>
35          <MenubarSeparator />
36          <MenubarGroup>
37            <MenubarItem>تیم</MenubarItem>
38            <MenubarItem>تنظیمات</MenubarItem>
39          </MenubarGroup>
40        </MenubarContent>
41      </MenubarMenu>
42    </Menubar>
43  );
44}

زیرمنو (Submenu)

استفاده از MenubarSub برای ایجاد زیرمنوهای تودرتو

مشاهده کد
1import {
2  Menubar,
3  MenubarContent,
4  MenubarItem,
5  MenubarMenu,
6  MenubarSeparator,
7  MenubarShortcut,
8  MenubarSub,
9  MenubarSubContent,
10  MenubarSubTrigger,
11  MenubarTrigger,
12} from "@/components/ui/menubar";
13
14export default function SubmenuExample() {
15  return (
16    <Menubar className="w-72">
17      <MenubarMenu>
18        <MenubarTrigger>فایل</MenubarTrigger>
19        <MenubarContent>
20          <MenubarSub>
21            <MenubarSubTrigger>اشتراک</MenubarSubTrigger>
22            <MenubarSubContent>
23              <MenubarItem>لینک ایمیل</MenubarItem>
24              <MenubarItem>پیام‌ها</MenubarItem>
25              <MenubarItem>یادداشت‌ها</MenubarItem>
26            </MenubarSubContent>
27          </MenubarSub>
28          <MenubarSeparator />
29          <MenubarItem>
30            چاپ... <MenubarShortcut>⌘P</MenubarShortcut>
31          </MenubarItem>
32        </MenubarContent>
33      </MenubarMenu>
34      <MenubarMenu>
35        <MenubarTrigger>ویرایش</MenubarTrigger>
36        <MenubarContent>
37          <MenubarItem>
38            تراجع <MenubarShortcut>⌘Z</MenubarShortcut>
39          </MenubarItem>
40          <MenubarItem>
41            انجام مجدد <MenubarShortcut>⇧⌘Z</MenubarShortcut>
42          </MenubarItem>
43          <MenubarSeparator />
44          <MenubarSub>
45            <MenubarSubTrigger>جستجو</MenubarSubTrigger>
46            <MenubarSubContent>
47              <MenubarItem>جستجو در وب</MenubarItem>
48            </MenubarSubContent>
49          </MenubarSub>
50          <MenubarSeparator />
51          <MenubarItem>برش</MenubarItem>
52          <MenubarItem>کپی</MenubarItem>
53          <MenubarItem>چسباندن</MenubarItem>
54        </MenubarContent>
55      </MenubarMenu>
56    </Menubar>
57  );
58}

کلیدهای میانبر (Shortcuts)

اضافه کردن MenubarShortcut برای نمایش راهنمای کیبورد

مشاهده کد
1import {
2  Menubar,
3  MenubarContent,
4  MenubarGroup,
5  MenubarItem,
6  MenubarMenu,
7  MenubarSeparator,
8  MenubarShortcut,
9  MenubarTrigger,
10} from "@/components/ui/menubar";
11
12export default function ShortcutsExample() {
13  return (
14    <Menubar className="w-72">
15      <MenubarMenu>
16        <MenubarTrigger>فایل</MenubarTrigger>
17        <MenubarContent>
18          <MenubarGroup>
19            <MenubarItem>
20              تب جدید <MenubarShortcut>⌘T</MenubarShortcut>
21            </MenubarItem>
22            <MenubarItem>
23              پنجره جدید <MenubarShortcut>⌘N</MenubarShortcut>
24            </MenubarItem>
25            <MenubarItem disabled>پنجره ناشناس جدید</MenubarItem>
26          </MenubarGroup>
27          <MenubarSeparator />
28          <MenubarGroup>
29            <MenubarItem>
30              چاپ... <MenubarShortcut>⌘P</MenubarShortcut>
31            </MenubarItem>
32          </MenubarGroup>
33        </MenubarContent>
34      </MenubarMenu>
35      <MenubarMenu>
36        <MenubarTrigger>ویرایش</MenubarTrigger>
37        <MenubarContent>
38          <MenubarGroup>
39            <MenubarItem>
40              تراجع <MenubarShortcut>⌘Z</MenubarShortcut>
41            </MenubarItem>
42            <MenubarItem>
43              انجام مجدد <MenubarShortcut>⇧⌘Z</MenubarShortcut>
44            </MenubarItem>
45          </MenubarGroup>
46          <MenubarSeparator />
47          <MenubarGroup>
48            <MenubarItem>برش</MenubarItem>
49            <MenubarItem>کپی</MenubarItem>
50            <MenubarItem>چسباندن</MenubarItem>
51          </MenubarGroup>
52        </MenubarContent>
53      </MenubarMenu>
54    </Menubar>
55  );
56}

آیکون‌ها (Icons)

ترکیب آیکون‌ها با variant مخرب برای اقدامات حذف

مشاهده کد
1import {
2  Menubar,
3  MenubarContent,
4  MenubarGroup,
5  MenubarItem,
6  MenubarMenu,
7  MenubarSeparator,
8  MenubarShortcut,
9  MenubarTrigger,
10} from "@/components/ui/menubar";
11import {
12  FileIcon,
13  FolderIcon,
14  HelpCircleIcon,
15  SaveIcon,
16  SettingsIcon,
17  TrashIcon,
18} from "lucide-react";
19
20export default function IconsExample() {
21  return (
22    <Menubar className="w-72">
23      <MenubarMenu>
24        <MenubarTrigger>فایل</MenubarTrigger>
25        <MenubarContent>
26          <MenubarItem>
27            <FileIcon className="me-2 h-4 w-4" />
28            فایل جدید <MenubarShortcut>⌘N</MenubarShortcut>
29          </MenubarItem>
30          <MenubarItem>
31            <FolderIcon className="me-2 h-4 w-4" />
32            باز کردن پوشه
33          </MenubarItem>
34          <MenubarSeparator />
35          <MenubarItem>
36            <SaveIcon className="me-2 h-4 w-4" />
37            ذخیره <MenubarShortcut>⌘S</MenubarShortcut>
38          </MenubarItem>
39        </MenubarContent>
40      </MenubarMenu>
41      <MenubarMenu>
42        <MenubarTrigger>بیشتر</MenubarTrigger>
43        <MenubarContent>
44          <MenubarGroup>
45            <MenubarItem>
46              <SettingsIcon className="me-2 h-4 w-4" />
47              تنظیمات
48            </MenubarItem>
49            <MenubarItem>
50              <HelpCircleIcon className="me-2 h-4 w-4" />
51              راهنما
52            </MenubarItem>
53            <MenubarSeparator />
54            <MenubarItem variant="destructive">
55              <TrashIcon className="me-2 h-4 w-4" />
56              حذف
57            </MenubarItem>
58          </MenubarGroup>
59        </MenubarContent>
60      </MenubarMenu>
61    </Menubar>
62  );
63}

چک‌باکس‌ها (Checkboxes)

استفاده از MenubarCheckboxItem برای گزینه‌های قابل تغییر

مشاهده کد
1import {
2  Menubar,
3  MenubarCheckboxItem,
4  MenubarContent,
5  MenubarGroup,
6  MenubarItem,
7  MenubarMenu,
8  MenubarSeparator,
9  MenubarShortcut,
10  MenubarTrigger,
11} from "@/components/ui/menubar";
12
13export default function CheckboxExample() {
14  return (
15    <Menubar className="w-72">
16      <MenubarMenu>
17        <MenubarTrigger>نمایش</MenubarTrigger>
18        <MenubarContent className="w-64">
19          <MenubarCheckboxItem>همیشه نمایش نوار نشانک‌ها</MenubarCheckboxItem>
20          <MenubarCheckboxItem checked>
21            همیشه نمایش آدرس کامل
22          </MenubarCheckboxItem>
23          <MenubarSeparator />
24          <MenubarItem inset>
25            بارگذاری مجدد <MenubarShortcut>⌘R</MenubarShortcut>
26          </MenubarItem>
27          <MenubarItem disabled inset>
28            بارگذاری اجباری <MenubarShortcut>⇧⌘R</MenubarShortcut>
29          </MenubarItem>
30        </MenubarContent>
31      </MenubarMenu>
32      <MenubarMenu>
33        <MenubarTrigger>قالب</MenubarTrigger>
34        <MenubarContent>
35          <MenubarCheckboxItem checked>خط خورده</MenubarCheckboxItem>
36          <MenubarCheckboxItem>کد</MenubarCheckboxItem>
37          <MenubarCheckboxItem>بالانویس</MenubarCheckboxItem>
38        </MenubarContent>
39      </MenubarMenu>
40    </Menubar>
41  );
42}

گروه رادیویی (Radio Group)

استفاده از MenubarRadioGroup برای انتخاب‌های انحصاری

مشاهده کد
1"use client";
2
3import * as React from "react";
4import {
5  Menubar,
6  MenubarContent,
7  MenubarItem,
8  MenubarMenu,
9  MenubarRadioGroup,
10  MenubarRadioItem,
11  MenubarSeparator,
12  MenubarTrigger,
13} from "@/components/ui/menubar";
14
15export default function RadioExample() {
16  const [user, setUser] = React.useState("benoit");
17  const [theme, setTheme] = React.useState("system");
18
19  return (
20    <Menubar className="w-72">
21      <MenubarMenu>
22        <MenubarTrigger>پروفایل‌ها</MenubarTrigger>
23        <MenubarContent>
24          <MenubarRadioGroup value={user} onValueChange={setUser}>
25            <MenubarRadioItem value="andy">اندی</MenubarRadioItem>
26            <MenubarRadioItem value="benoit">بنوا</MenubarRadioItem>
27            <MenubarRadioItem value="luis">لوئیس</MenubarRadioItem>
28          </MenubarRadioGroup>
29          <MenubarSeparator />
30          <MenubarItem inset>ویرایش...</MenubarItem>
31          <MenubarItem inset>افزودن پروفایل...</MenubarItem>
32        </MenubarContent>
33      </MenubarMenu>
34      <MenubarMenu>
35        <MenubarTrigger>تم</MenubarTrigger>
36        <MenubarContent>
37          <MenubarRadioGroup value={theme} onValueChange={setTheme}>
38            <MenubarRadioItem value="light">روشن</MenubarRadioItem>
39            <MenubarRadioItem value="dark">تاریک</MenubarRadioItem>
40            <MenubarRadioItem value="system">سیستم</MenubarRadioItem>
41          </MenubarRadioGroup>
42        </MenubarContent>
43      </MenubarMenu>
44    </Menubar>
45  );
46}

مرجع API (API Reference)

Menubar

کامپوننت اصلی نوار منو

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestringundefinedمقدار منوی فعال (کنترل‌شده)
defaultValuestringundefinedمقدار پیش‌فرض منوی فعال
onValueChange(value: string) => voidundefinedتابع فراخوانی هنگام تغییر منوی فعال

MenubarTrigger

دکمه‌ای که منو را باز و بسته می‌کند

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
asChildbooleanfalseترکیب با فرزند به عنوان trigger

MenubarContent

محتوای منو که هنگام باز شدن نمایش داده می‌شود

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestringundefinedکلاس‌های CSS سفارشی
align"start" | "center" | "end""start"تراز کردن نسبت به trigger
sideOffsetnumber8فاصله از trigger (پیکسل)

MenubarItem

آیتم قابل انتخاب در منو

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
disabledbooleanfalseغیرفعال کردن آیتم
onSelect(event: Event) => voidundefinedتابع فراخوانی هنگام انتخاب
insetbooleanfalseاضافه کردن padding برای تراز با آیتم‌های دارای آیکون
variant"default" | "destructive""default"نوع آیتم (destructive برای اقدامات حذف)

MenubarCheckboxItem

آیتمی که می‌تواند چک شود

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
checkedboolean | 'indeterminate'falseوضعیت چک شده
onCheckedChange(checked: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت
disabledbooleanfalseغیرفعال کردن آیتم

MenubarRadioGroup

گروهی از آیتم‌های رادیویی

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestringundefinedمقدار انتخاب شده
onValueChange(value: string) => voidundefinedتابع فراخوانی هنگام تغییر مقدار

MenubarRadioItem

آیتم رادیویی در گروه

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestring-مقدار آیتم (الزامی)
disabledbooleanfalseغیرفعال کردن آیتم

MenubarSub

زیرمنو تودرتو

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
openbooleanundefinedوضعیت باز/بسته بودن زیرمنو (کنترل‌شده)
defaultOpenbooleanfalseوضعیت پیش‌فرض زیرمنو
onOpenChange(open: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت زیرمنو

دسترسی‌پذیری (Accessibility)

کیبورد (Keyboard)

  • Space یا Enter - باز کردن منو یا فعال کردن آیتم
  • Arrow Down - حرکت به آیتم بعدی
  • Arrow Up - حرکت به آیتم قبلی
  • Arrow Right / Arrow Left - باز یا بستن زیرمنو
  • Esc - بستن منو

فوکوس (Focus)

نوار منو دارای مدیریت فوکوس کامل است و می‌توان با کیبورد بین منوها و آیتم‌ها حرکت کرد. فوکوس به صورت خودکار به اولین آیتم منتقل می‌شود

ARIA (Roles & Attributes)

کامپوننت از الگوی Menu Bar WAI-ARIA پیروی می‌کند و از roving tabindex برای مدیریت حرکت فوکوس استفاده می‌کند

بهترین شیوه‌ها (Best Practices)

گروه‌بندی آیتم‌ها

از MenubarGroup و MenubarSeparator برای سازماندهی آیتم‌های مرتبط استفاده کنید. این کار باعث می‌شود کاربران راحت‌تر بتوانند گزینه مورد نظر خود را پیدا کنند.

استفاده از آیکون‌ها

آیکون‌ها به کاربران کمک می‌کنند تا سریع‌تر گزینه‌ها را شناسایی کنند. همیشه آیکون را قبل از متن قرار دهید و از کلاس me-2 برای فاصله‌گذاری استفاده کنید.

اقدامات مخرب

برای اقدامات برگشت‌ناپذیر مانند حذف، از variant="destructive" استفاده کنید و آن‌ها را در انتهای منو قرار دهید. همچنین می‌توانید یک جداکننده قبل از آن‌ها اضافه کنید.

کلیدهای میانبر

از MenubarShortcut برای نمایش کلیدهای میانبر استفاده کنید. این کار به کاربران پیشرفته کمک می‌کند تا سریع‌تر با برنامه شما کار کنند.

زیرمنوها

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

نحوه استفاده (Usage)

1import {
2  Menubar,
3  MenubarContent,
4  MenubarGroup,
5  MenubarItem,
6  MenubarMenu,
7  MenubarSeparator,
8  MenubarShortcut,
9  MenubarTrigger,
10} from "@/components/ui/menubar";
11
12export default function Example() {
13  return (
14    <Menubar className="w-72">
15      <MenubarMenu>
16        <MenubarTrigger>فایل</MenubarTrigger>
17        <MenubarContent>
18          <MenubarGroup>
19            <MenubarItem>
20              تب جدید <MenubarShortcut>⌘T</MenubarShortcut>
21            </MenubarItem>
22            <MenubarItem>پنجره جدید</MenubarItem>
23          </MenubarGroup>
24          <MenubarSeparator />
25          <MenubarGroup>
26            <MenubarItem>اشتراک</MenubarItem>
27            <MenubarItem>چاپ</MenubarItem>
28          </MenubarGroup>
29        </MenubarContent>
30      </MenubarMenu>
31      <MenubarMenu>
32        <MenubarTrigger>ویرایش</MenubarTrigger>
33        <MenubarContent>
34          <MenubarGroup>
35            <MenubarItem>پروفایل</MenubarItem>
36            <MenubarItem>صورتحساب</MenubarItem>
37          </MenubarGroup>
38          <MenubarSeparator />
39          <MenubarGroup>
40            <MenubarItem>تیم</MenubarItem>
41            <MenubarItem>تنظیمات</MenubarItem>
42          </MenubarGroup>
43        </MenubarContent>
44      </MenubarMenu>
45    </Menubar>
46  );
47}