منوی زمینه (Context Menu)

منویی از اقدامات که با کلیک راست یا لمس طولانی روی یک ناحیه ظاهر می‌شود. مناسب برای نمایش اکشن‌های مرتبط با محتوای خاص بدون شلوغ کردن رابط کاربری اصلی.

نصب (Installation)

1npx @quark-lab/rad-ui add context-menu

نمونه‌ها (Examples)

نمونه پایه (Basic)

منوی زمینه ساده با چند اکشن عمومی.

برای دیدن منو کلیک راست کنید
مشاهده کد
1import {
2  ContextMenu,
3  ContextMenuContent,
4  ContextMenuItem,
5  ContextMenuTrigger,
6} from "@/components/ui/context-menu";
7
8export default function BasicContextMenuExample() {
9  return (
10    <ContextMenu>
11      <ContextMenuTrigger className="flex h-24 w-full max-w-sm items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
12        برای دیدن منو کلیک راست کنید
13      </ContextMenuTrigger>
14      <ContextMenuContent>
15        <ContextMenuItem>پروفایل</ContextMenuItem>
16        <ContextMenuItem>صورت‌حساب</ContextMenuItem>
17        <ContextMenuItem>تیم</ContextMenuItem>
18        <ContextMenuItem>اشتراک</ContextMenuItem>
19      </ContextMenuContent>
20    </ContextMenu>
21  );
22}
23

با آیکون (With Icons)

افزودن آیکون به آیتم‌ها برای اسکن سریع‌تر.

کلیک راست با آیکون
مشاهده کد
1import {
2  ContextMenu,
3  ContextMenuContent,
4  ContextMenuItem,
5  ContextMenuTrigger,
6} from "@/components/ui/context-menu";
7import { User, CreditCard, Users, Settings } from "lucide-react";
8
9export default function IconsContextMenuExample() {
10  return (
11    <ContextMenu>
12      <ContextMenuTrigger className="flex h-24 w-full max-w-sm items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
13        کلیک راست با آیکون
14      </ContextMenuTrigger>
15      <ContextMenuContent>
16        <ContextMenuItem className="flex items-center gap-2">
17          <User className="h-4 w-4" />
18          <span>پروفایل</span>
19        </ContextMenuItem>
20        <ContextMenuItem className="flex items-center gap-2">
21          <CreditCard className="h-4 w-4" />
22          <span>پرداخت</span>
23        </ContextMenuItem>
24        <ContextMenuItem className="flex items-center gap-2">
25          <Users className="h-4 w-4" />
26          <span>اعضای تیم</span>
27        </ContextMenuItem>
28        <ContextMenuItem className="flex items-center gap-2">
29          <Settings className="h-4 w-4" />
30          <span>تنظیمات</span>
31        </ContextMenuItem>
32      </ContextMenuContent>
33    </ContextMenu>
34  );
35}
36

گروه‌ها و جداکننده‌ها (Groups)

گروه‌بندی اکشن‌ها و جداسازی آن‌ها با Separator.

کلیک راست با گروه‌ها
مشاهده کد
1import {
2  ContextMenu,
3  ContextMenuContent,
4  ContextMenuGroup,
5  ContextMenuItem,
6  ContextMenuLabel,
7  ContextMenuSeparator,
8  ContextMenuTrigger,
9} from "@/components/ui/context-menu";
10
11export default function GroupsContextMenuExample() {
12  return (
13    <ContextMenu>
14      <ContextMenuTrigger className="flex h-24 w-full max-w-sm items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
15        کلیک راست با گروه‌ها
16      </ContextMenuTrigger>
17      <ContextMenuContent>
18        <ContextMenuLabel inset>حساب کاربری</ContextMenuLabel>
19        <ContextMenuGroup>
20          <ContextMenuItem>پروفایل</ContextMenuItem>
21          <ContextMenuItem>صورت‌حساب</ContextMenuItem>
22        </ContextMenuGroup>
23        <ContextMenuSeparator />
24        <ContextMenuLabel inset>تیم</ContextMenuLabel>
25        <ContextMenuGroup>
26          <ContextMenuItem>اعضای تیم</ContextMenuItem>
27          <ContextMenuItem>دعوت به تیم</ContextMenuItem>
28        </ContextMenuGroup>
29      </ContextMenuContent>
30    </ContextMenu>
31  );
32}
33

چک‌باکس و گزینه‌های رادیویی (Checkbox & Radio)

استفاده از آیتم‌های چک‌باکس و رادیویی برای تنظیمات سریع.

کلیک راست برای تنظیمات
مشاهده کد
1"use client";
2
3import * as React from "react";
4import {
5  ContextMenu,
6  ContextMenuCheckboxItem,
7  ContextMenuContent,
8  ContextMenuItem,
9  ContextMenuLabel,
10  ContextMenuRadioGroup,
11  ContextMenuRadioItem,
12  ContextMenuSeparator,
13  ContextMenuTrigger,
14} from "@/components/ui/context-menu";
15
16export default function CheckboxRadioContextMenuExample() {
17  const [showLineNumbers, setShowLineNumbers] = React.useState(true);
18  const [theme, setTheme] = React.useState("dark");
19
20  return (
21    <ContextMenu>
22      <ContextMenuTrigger className="flex h-24 w-full max-w-sm items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
23        کلیک راست برای تنظیمات
24      </ContextMenuTrigger>
25      <ContextMenuContent>
26        <ContextMenuLabel inset>نمایش</ContextMenuLabel>
27        <ContextMenuCheckboxItem
28          checked={showLineNumbers}
29          onCheckedChange={(v) => setShowLineNumbers(!!v)}
30        >
31          نمایش شماره خطوط
32        </ContextMenuCheckboxItem>
33        <ContextMenuSeparator />
34        <ContextMenuLabel inset>تم</ContextMenuLabel>
35        <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
36          <ContextMenuRadioItem value="light">روشن</ContextMenuRadioItem>
37          <ContextMenuRadioItem value="dark">تاریک</ContextMenuRadioItem>
38          <ContextMenuRadioItem value="system">سیستم</ContextMenuRadioItem>
39        </ContextMenuRadioGroup>
40      </ContextMenuContent>
41    </ContextMenu>
42  );
43}
44

مرجع API (API Reference)

ContextMenu

کامپوننت ریشه که رفتار باز/بسته شدن منوی زمینه را مدیریت می‌کند.

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

ContextMenuTrigger

ناحیه‌ای که با کلیک راست روی آن منوی زمینه باز می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
asChildbooleanfalseدر صورت true شدن، عنصر فرزند به عنوان تریگر استفاده می‌شود (بدون افزودن wrapper اضافی).
classNamestring-کلاس‌های CSS سفارشی برای ناحیه‌ای که کلیک راست روی آن انجام می‌شود.

ContextMenuItem

آیتم‌های ساده در منوی زمینه.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
insetbooleanfalseافزودن فاصله داخلی بیشتر برای هم‌تراز شدن با آیکون‌ها یا زیرمنوها.
disabledbooleanfalseغیرفعال کردن آیتم منو.
classNamestring-کلاس‌های CSS سفارشی.

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

کیبورد (Keyboard)

  • Arrow Down / Arrow Up — حرکت بین آیتم‌های منو.
  • Enter — فعال کردن آیتم انتخاب‌شده.
  • Escape — بستن منوی زمینه.

استفاده با صفحه‌خوان

منوی زمینه بر اساس Radix Context Menu ساخته شده و از نقش‌ها و ویژگی‌های ARIA مناسب برای منوها و آیتم‌های منو استفاده می‌کند.

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

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

اکشن‌های اصلی را همیشه به صورت دکمه یا منوی قابل مشاهده نمایش دهید. منوی زمینه برای اکشن‌های تکمیلی و ثانویه مناسب است.

توضیح رفتار

در صورت نیاز، یک متن راهنما (hint) در رابط کاربری قرار دهید تا کاربر بداند می‌تواند روی یک ناحیه کلیک راست کند.

گروه‌بندی منظم

اکشن‌های مرتبط را در کنار هم و با استفاده از Label و Separator گروه‌بندی کنید تا منو واضح‌تر و قابل اسکن‌تر باشد.

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

1import {
2  ContextMenu,
3  ContextMenuContent,
4  ContextMenuItem,
5  ContextMenuLabel,
6  ContextMenuSeparator,
7  ContextMenuTrigger,
8} from "@/components/ui/context-menu";
9
10export default function ContextMenuUsageExample() {
11  return (
12    <ContextMenu>
13      <ContextMenuTrigger className="flex h-24 w-full max-w-sm items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
14        روی این ناحیه کلیک راست کنید
15      </ContextMenuTrigger>
16      <ContextMenuContent>
17        <ContextMenuLabel inset>حساب کاربری</ContextMenuLabel>
18        <ContextMenuItem>پروفایل</ContextMenuItem>
19        <ContextMenuItem>صورت‌حساب</ContextMenuItem>
20        <ContextMenuSeparator />
21        <ContextMenuItem>خروج</ContextMenuItem>
22      </ContextMenuContent>
23    </ContextMenu>
24  );
25}
26