صفحه‌کلید (Keyboard)

نمایش کلیدها و میانبرهای صفحه‌کلید.

نصب (Installation)

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

نمونه‌ها (Examples)

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

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

CtrlShiftAltEnterTabEsc

مشاهده کد

1import { Kbd } from "@/components/ui/kbd";
2
3export default function BasicExample() {
4  return (
5    <div className="flex items-center gap-4 flex-wrap">
6      <Kbd>Ctrl</Kbd>
7      <Kbd>Shift</Kbd>
8      <Kbd>Alt</Kbd>
9      <Kbd>Enter</Kbd>
10      <Kbd>Tab</Kbd>
11      <Kbd>Esc</Kbd>
12    </div>
13  );
14}
15

میانبرهای صفحه‌کلید (Keyboard Shortcuts)

با استفاده از KbdGroup می‌توانید چند کلید را کنار هم نمایش دهید.

کپی:

Ctrl+C

قص:

Ctrl+X

چسباندن:

Ctrl+V

بازگشت:

Ctrl+Z

تکرار:

Ctrl+Y

مشاهده کد

1import { Kbd, KbdGroup } from "@/components/ui/kbd";
2
3export default function ShortcutsExample() {
4  return (
5    <div className="space-y-4">
6      <div className="flex items-center gap-4">
7        <span className="text-sm min-w-[120px]">کپی:</span>
8        <KbdGroup>
9          <Kbd>Ctrl</Kbd>
10          <span className="text-muted-foreground">+</span>
11          <Kbd>C</Kbd>
12        </KbdGroup>
13      </div>
14      <div className="flex items-center gap-4">
15        <span className="text-sm min-w-[120px]">قص:</span>
16        <KbdGroup>
17          <Kbd>Ctrl</Kbd>
18          <span className="text-muted-foreground">+</span>
19          <Kbd>X</Kbd>
20        </KbdGroup>
21      </div>
22      <div className="flex items-center gap-4">
23        <span className="text-sm min-w-[120px]">چسباندن:</span>
24        <KbdGroup>
25          <Kbd>Ctrl</Kbd>
26          <span className="text-muted-foreground">+</span>
27          <Kbd>V</Kbd>
28        </KbdGroup>
29      </div>
30      <div className="flex items-center gap-4">
31        <span className="text-sm min-w-[120px]">بازگشت:</span>
32        <KbdGroup>
33          <Kbd>Ctrl</Kbd>
34          <span className="text-muted-foreground">+</span>
35          <Kbd>Z</Kbd>
36        </KbdGroup>
37      </div>
38      <div className="flex items-center gap-4">
39        <span className="text-sm min-w-[120px]">تکرار:</span>
40        <KbdGroup>
41          <Kbd>Ctrl</Kbd>
42          <span className="text-muted-foreground">+</span>
43          <Kbd>Y</Kbd>
44        </KbdGroup>
45      </div>
46    </div>
47  );
48}
49

میانبرهای سیستم‌عامل (Platform Shortcuts)

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

Windows / Linux

ذخیره

Ctrl+S

جستجو

Ctrl+F

انتخاب همه

Ctrl+A

تب جدید

Ctrl+T

macOS

ذخیره

⌘+S

جستجو

⌘+F

انتخاب همه

⌘+A

تب جدید

⌘+T

مشاهده کد

1import { Kbd, KbdGroup } from "@/components/ui/kbd";
2
3export default function PlatformShortcutsExample() {
4  return (
5    <div className="grid md:grid-cols-2 gap-6 w-full">
6      {/* Windows/Linux */}
7      <div className="p-6 rounded-lg bg-card border border-border">
8        <h3 className="text-lg font-semibold mb-4">Windows / Linux</h3>
9        <div className="space-y-3">
10          <div className="flex items-center justify-between">
11            <span className="text-sm text-muted-foreground">ذخیره</span>
12            <KbdGroup>
13              <Kbd>Ctrl</Kbd>
14              <span className="text-muted-foreground">+</span>
15              <Kbd>S</Kbd>
16            </KbdGroup>
17          </div>
18          <div className="flex items-center justify-between">
19            <span className="text-sm text-muted-foreground">جستجو</span>
20            <KbdGroup>
21              <Kbd>Ctrl</Kbd>
22              <span className="text-muted-foreground">+</span>
23              <Kbd>F</Kbd>
24            </KbdGroup>
25          </div>
26          <div className="flex items-center justify-between">
27            <span className="text-sm text-muted-foreground">انتخاب همه</span>
28            <KbdGroup>
29              <Kbd>Ctrl</Kbd>
30              <span className="text-muted-foreground">+</span>
31              <Kbd>A</Kbd>
32            </KbdGroup>
33          </div>
34          <div className="flex items-center justify-between">
35            <span className="text-sm text-muted-foreground">تب جدید</span>
36            <KbdGroup>
37              <Kbd>Ctrl</Kbd>
38              <span className="text-muted-foreground">+</span>
39              <Kbd>T</Kbd>
40            </KbdGroup>
41          </div>
42        </div>
43      </div>
44
45      {/* macOS */}
46      <div className="p-6 rounded-lg bg-card border border-border">
47        <h3 className="text-lg font-semibold mb-4">macOS</h3>
48        <div className="space-y-3">
49          <div className="flex items-center justify-between">
50            <span className="text-sm text-muted-foreground">ذخیره</span>
51            <KbdGroup>
52              <Kbd>⌘</Kbd>
53              <span className="text-muted-foreground">+</span>
54              <Kbd>S</Kbd>
55            </KbdGroup>
56          </div>
57          <div className="flex items-center justify-between">
58            <span className="text-sm text-muted-foreground">جستجو</span>
59            <KbdGroup>
60              <Kbd>⌘</Kbd>
61              <span className="text-muted-foreground">+</span>
62              <Kbd>F</Kbd>
63            </KbdGroup>
64          </div>
65          <div className="flex items-center justify-between">
66            <span className="text-sm text-muted-foreground">انتخاب همه</span>
67            <KbdGroup>
68              <Kbd>⌘</Kbd>
69              <span className="text-muted-foreground">+</span>
70              <Kbd>A</Kbd>
71            </KbdGroup>
72          </div>
73          <div className="flex items-center justify-between">
74            <span className="text-sm text-muted-foreground">تب جدید</span>
75            <KbdGroup>
76              <Kbd>⌘</Kbd>
77              <span className="text-muted-foreground">+</span>
78              <Kbd>T</Kbd>
79            </KbdGroup>
80          </div>
81        </div>
82      </div>
83    </div>
84  );
85}
86

کلیدهای خاص (Special Keys)

استفاده از نمادهای یونیکد برای کلیدهای ویژه.

⌘Command

⌥Option

⇧Shift

⌃Control

↩Return

⌫Delete

⎋Escape

→Arrow

مشاهده کد

1import { Kbd } from "@/components/ui/kbd";
2
3export default function SpecialKeysExample() {
4  return (
5    <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
6      <div className="flex flex-col items-center gap-2">
7        <Kbd>⌘</Kbd>
8        <span className="text-xs text-muted-foreground">Command</span>
9      </div>
10      <div className="flex flex-col items-center gap-2">
11        <Kbd>⌥</Kbd>
12        <span className="text-xs text-muted-foreground">Option</span>
13      </div>
14      <div className="flex flex-col items-center gap-2">
15        <Kbd>⇧</Kbd>
16        <span className="text-xs text-muted-foreground">Shift</span>
17      </div>
18      <div className="flex flex-col items-center gap-2">
19        <Kbd>⌃</Kbd>
20        <span className="text-xs text-muted-foreground">Control</span>
21      </div>
22      <div className="flex flex-col items-center gap-2">
23        <Kbd>↩</Kbd>
24        <span className="text-xs text-muted-foreground">Return</span>
25      </div>
26      <div className="flex flex-col items-center gap-2">
27        <Kbd>⌫</Kbd>
28        <span className="text-xs text-muted-foreground">Delete</span>
29      </div>
30      <div className="flex flex-col items-center gap-2">
31        <Kbd>⎋</Kbd>
32        <span className="text-xs text-muted-foreground">Escape</span>
33      </div>
34      <div className="flex flex-col items-center gap-2">
35        <Kbd>→</Kbd>
36        <span className="text-xs text-muted-foreground">Arrow</span>
37      </div>
38    </div>
39  );
40}
41

مثال‌های کاربردی (Practical Examples)

با دکمه‌ها (With Buttons)

ترکیب دکمه‌ها با راهنمای کلید میانبر.

مشاهده کد

1import { Kbd, KbdGroup } from "@/components/ui/kbd";
2import { Button } from "@/components/ui/button";
3import { Search, Copy, Save } from "lucide-react";
4
5export default function WithButtonsExample() {
6  return (
7    <div className="flex flex-wrap gap-3">
8      <Button variant="outline" className="gap-2">
9        <Search className="h-4 w-4" />
10        جستجو
11        <KbdGroup>
12          <Kbd>Ctrl</Kbd>
13          <Kbd>K</Kbd>
14        </KbdGroup>
15      </Button>
16      <Button variant="outline" className="gap-2">
17        <Copy className="h-4 w-4" />
18        کپی
19        <Kbd>Ctrl+C</Kbd>
20      </Button>
21      <Button variant="outline" className="gap-2">
22        <Save className="h-4 w-4" />
23        ذخیره
24        <Kbd>Ctrl+S</Kbd>
25      </Button>
26    </div>
27  );
28}
29

راهنمای میانبرها (Shortcut Cheatsheet)

یک لیست کامل از میانبرهای کاربردی.

ویرایش

بازگشت

Ctrl+Z

تکرار

Ctrl+Y

کپی

Ctrl+C

چسباندن

Ctrl+V

ناوبری

جستجو

Ctrl+F

رفتن به خط

Ctrl+G

پالت دستورات

Ctrl+P

تنظیمات

Ctrl+,

مشاهده کد

1import { Kbd, KbdGroup } from "@/components/ui/kbd";
2
3export default function CheatsheetExample() {
4  return (
5    <div className="grid md:grid-cols-2 gap-4 w-full">
6      <div className="space-y-3">
7        <h4 className="font-semibold text-sm mb-2">ویرایش</h4>
8        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
9          <span className="text-sm">بازگشت</span>
10          <KbdGroup>
11            <Kbd>Ctrl</Kbd>
12            <span className="text-muted-foreground">+</span>
13            <Kbd>Z</Kbd>
14          </KbdGroup>
15        </div>
16        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
17          <span className="text-sm">تکرار</span>
18          <KbdGroup>
19            <Kbd>Ctrl</Kbd>
20            <span className="text-muted-foreground">+</span>
21            <Kbd>Y</Kbd>
22          </KbdGroup>
23        </div>
24        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
25          <span className="text-sm">کپی</span>
26          <KbdGroup>
27            <Kbd>Ctrl</Kbd>
28            <span className="text-muted-foreground">+</span>
29            <Kbd>C</Kbd>
30          </KbdGroup>
31        </div>
32        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
33          <span className="text-sm">چسباندن</span>
34          <KbdGroup>
35            <Kbd>Ctrl</Kbd>
36            <span className="text-muted-foreground">+</span>
37            <Kbd>V</Kbd>
38          </KbdGroup>
39        </div>
40      </div>
41
42      <div className="space-y-3">
43        <h4 className="font-semibold text-sm mb-2">ناوبری</h4>
44        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
45          <span className="text-sm">جستجو</span>
46          <KbdGroup>
47            <Kbd>Ctrl</Kbd>
48            <span className="text-muted-foreground">+</span>
49            <Kbd>F</Kbd>
50          </KbdGroup>
51        </div>
52        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
53          <span className="text-sm">رفتن به خط</span>
54          <KbdGroup>
55            <Kbd>Ctrl</Kbd>
56            <span className="text-muted-foreground">+</span>
57            <Kbd>G</Kbd>
58          </KbdGroup>
59        </div>
60        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
61          <span className="text-sm">پالت دستورات</span>
62          <KbdGroup>
63            <Kbd>Ctrl</Kbd>
64            <span className="text-muted-foreground">+</span>
65            <Kbd>P</Kbd>
66          </KbdGroup>
67        </div>
68        <div className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-muted transition-colors">
69          <span className="text-sm">تنظیمات</span>
70          <KbdGroup>
71            <Kbd>Ctrl</Kbd>
72            <span className="text-muted-foreground">+</span>
73            <Kbd>,</Kbd>
74          </KbdGroup>
75        </div>
76      </div>
77    </div>
78  );
79}
80

نوار ابزار (Toolbar)

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

مشاهده کد

1import { Kbd, Button } from "@/components/ui/kbd";
2import { Copy, Save, Undo, Redo } from "lucide-react";
3
4export default function ToolbarExample() {
5  return (
6    <div className="flex items-center gap-2 flex-wrap">
7      <Button size="sm" variant="ghost" className="gap-2">
8        <Undo className="h-4 w-4" />
9        <Kbd>Ctrl+Z</Kbd>
10      </Button>
11      <Button size="sm" variant="ghost" className="gap-2">
12        <Redo className="h-4 w-4" />
13        <Kbd>Ctrl+Y</Kbd>
14      </Button>
15      <div className="h-6 w-px bg-border mx-2" />
16      <Button size="sm" variant="ghost" className="gap-2">
17        <Copy className="h-4 w-4" />
18        <Kbd>Ctrl+C</Kbd>
19      </Button>
20      <Button size="sm" variant="ghost" className="gap-2">
21        <Save className="h-4 w-4" />
22        <Kbd>Ctrl+S</Kbd>
23      </Button>
24    </div>
25  );
26}
27

مرجع API (API Reference)

Kbd

پراپ‌های کامپوننت Kbd.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`children`	`ReactNode`	`undefined`	محتوای کلید (حرف یا نماد)
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی

KbdGroup

پراپ‌های کامپوننت KbdGroup.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`children`	`ReactNode`	`undefined`	کلیدهای Kbd به همراه جداکننده
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی

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

استفاده از المان kbd

این کامپوننت از المان HTML <kbd> استفاده می‌کند که به صورت معنایی نشان می‌دهد محتوا یک ورودی صفحه‌کلید است

غیرقابل تعامل

کلیدها به صورت pointer-events-none هستند و تنها برای نمایش استفاده می‌شوند، نه تعامل

محتوای واضح

از حروف و نمادهای واضح استفاده کنید تا کاربران به راحتی بتوانند آنها را تشخیص دهند

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

استفاده از نمادها

برای کلیدهای خاص macOS از نمادهای یونیکد (⌘, ⌥, ⇧) استفاده کنید. برای Windows/Linux از نام کلید (Ctrl, Alt, Shift) استفاده کنید

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

از KbdGroup برای نمایش میانبرهای چند کلیده استفاده کنید و بین کلیدها جداکننده (+) قرار دهید

سازگاری

در کل اپلیکیشن از یک فرمت واحد برای نمایش میانبرها استفاده کنید

کاربرد صحیح

از این کامپوننت تنها برای نمایش کلیدها استفاده کنید، نه برای دکمه‌های قابل کلیک