منوی زمینه (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) |
|---|---|---|---|
open | boolean | undefined | کنترل باز/بسته بودن منو در حالت کنترلشده. |
onOpenChange | (open: boolean) => void | undefined | تابع فراخوانی هنگام تغییر وضعیت باز/بسته. |
ContextMenuTrigger
ناحیهای که با کلیک راست روی آن منوی زمینه باز میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
asChild | boolean | false | در صورت true شدن، عنصر فرزند به عنوان تریگر استفاده میشود (بدون افزودن wrapper اضافی). |
className | string | - | کلاسهای CSS سفارشی برای ناحیهای که کلیک راست روی آن انجام میشود. |
ContextMenuItem
آیتمهای ساده در منوی زمینه.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
inset | boolean | false | افزودن فاصله داخلی بیشتر برای همتراز شدن با آیکونها یا زیرمنوها. |
disabled | boolean | false | غیرفعال کردن آیتم منو. |
className | string | - | کلاسهای 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