Context Menu

Stabilny

Akcje dla konkretnego obiektu, otwierane prawym przyciskiem myszy lub długim przytrzymaniem dokładnie tam, gdzie jest kursor — skrót, nigdy jedyna droga.

Kod źródłowy Base UI Rejestr

examples/context-menu/demo.tsx

Kliknij tutaj prawym przyciskiem

Instalacja

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/context-menu.json

Użycie

import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"

<ContextMenu>
  <ContextMenuTrigger className="rounded-xl border border-dashed p-10">
    Right-click here
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuGroup>
      <ContextMenuItem>Rename</ContextMenuItem>
      <ContextMenuItem>Duplicate</ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>

ContextMenuTrigger wyznacza obszar, który reaguje na kliknięcie prawym przyciskiem myszy (albo długie przytrzymanie na ekranie dotykowym). Menu otwiera się w miejscu kursora. Pozycje, grupy, podmenu, pozycje z polem wyboru i pozycje radiowe działają dokładnie tak samo jak w Dropdown Menu.

Przykłady

Wszystko, co może zawierać menu kontekstowe: skróty, wyłączoną pozycję, podmenu, pozycje z polem wyboru i grupę radiową z etykietą.

examples/context-menu/demo.tsx

Kliknij tutaj prawym przyciskiem

Elementy listy

Daj każdemu wierszowi własny ContextMenu, żeby akcje zawsze dotyczyły obiektu pod kursorem. Gdy menu jest otwarte, jego wyzwalacz dostaje atrybut data-popup-open — użyj go, żeby wiersz pozostał wyróżniony i było widać, na czym działa menu.

examples/context-menu/file-item.tsx

Obiekty na płótnie

W narzędziach projektowych, edytorach i mapach polecenia dotyczące pojedynczych obiektów opierają się na menu kontekstowym. Używaj dokładnie tego samego słownictwa co w głównych menu aplikacji i pokazuj te same skróty.

examples/context-menu/canvas.tsx

Ramka 1

Wytyczne

Kiedy używać

Aby przyspieszyć akcje na obiektach, którymi użytkownicy manipulują bezpośrednio: plikach, wierszach, warstwach na płótnie, wiadomościach.
W gęstych narzędziach obsługiwanych głównie myszą, w których widoczne przyciski akcji zagraciłyby interfejs.

Kiedy nie używać

Gdy ma być jedynym sposobem dotarcia do akcji. Kliknięcie prawym przyciskiem trudno odkryć, na większości urządzeń dotykowych w ogóle nie istnieje, a z klawiatury wywołuje się je niewygodnie. Każda pozycja musi być dostępna także z widocznej kontrolki — Dropdown Menu pod przyciskiem ⋯, paska narzędzi albo widoku szczegółów obiektu.
Tam, gdzie ludzie oczekują menu przeglądarki — np. na tekście, który chcą skopiować, albo na linkach, które chcą otworzyć w nowej karcie.

Odzwierciedlaj widoczne menu

Menu kontekstowe to skrót do poleceń, które już istnieją. Używaj tych samych etykiet, kolejności i skrótów co w menu ⋯ danego wiersza albo w pasku menu aplikacji, żeby ludzie uczyli się tego słownictwa tylko raz. Najczęstsze akcje umieszczaj na początku, a destrukcyjne — na końcu, za separatorem.

Wytyczne marki.pdf

Dobrze.Te same akcje są o jedno kliknięcie stąd, pod widocznym przyciskiem.

Wytyczne marki.pdf(opcje pod prawym przyciskiem myszy)

Źle.Akcje dostępne tylko pod prawym przyciskiem myszy są dla większości ludzi niewidoczne.

Im krócej, tym lepiej

Menu kontekstowe czyta się przy kursorze i w pośpiechu. Staraj się zmieścić w mniej niż dziesięciu pozycjach w dwóch–trzech grupach, unikaj więcej niż jednego poziomu podmenu i nigdy nie umieszczaj w menu dłuższych treści.

Dostępność

Context Menu opiera się na komponencie Context Menu z Base UI, który po otwarciu realizuje wzorzec WAI-ARIA menu (APG opisuje menu i paski menu na jednej stronie).

Klawisz	Działanie
`ShiftF10`	Gdy fokus jest w obszarze wyzwalacza, otwiera menu — to systemowy klawiaturowy odpowiednik kliknięcia prawym przyciskiem. To samo robi klawisz menu kontekstowego (ContextMenu) na klawiaturach dla Windows.
`↓↑`	Przenosi fokus między pozycjami, zapętlając się na końcach listy.
`HomeEnd`	Przenosi fokus na pierwszą lub ostatnią pozycję.
`→←`	Otwiera lub zamyka podmenu.
`EnterSpacja`	Aktywuje pozycję z fokusem.
`A–Z`	Przenosi fokus na następną pozycję zaczynającą się od wpisanych znaków.
`Esc`	Zamyka menu.

Dotyk. Długie przytrzymanie wyzwalacza otwiera menu, więc te same akcje działają na telefonach i tabletach.
Równoważność. Menu kontekstowe trudno odkryć za pomocą technologii wspomagających, dlatego widoczna alternatywa nie jest opcjonalna — to dzięki niej akcje są w ogóle dostępne.

Dokumentacja API

ContextMenu

Komponent główny. Przyjmuje propsy ContextMenu.Root z Base UI.

Prop	Typ	Domyślnie
`open` Kontrolowany stan otwarcia.	`boolean`	Brak wartości domyślnej
`defaultOpen` Początkowy stan otwarcia w trybie niekontrolowanym.	`boolean`	`false`
`onOpenChange` Wywoływana, gdy menu się otwiera lub zamyka.	`(open: boolean, details) => void`	Brak wartości domyślnej
`loopFocus` Czy fokus przesuwany strzałkami zapętla się na końcach listy.	`boolean`	`true`
`disabled` Wyłącza menu; zamiast niego pojawia się menu przeglądarki.	`boolean`	`false`

ContextMenuTrigger

Obszar, który nasłuchuje kliknięcia prawym przyciskiem i długiego przytrzymania. Renderuje <div> z klasą select-none; stylizuj go jak każdy kontener. Gdy jego menu jest otwarte, dostaje atrybut data-popup-open.

ContextMenuContent

Prop	Typ	Domyślnie
`side` Preferowana strona względem kursora.	`"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"`	`"right"`
`align` Wyrównanie względem pozycji kursora.	`"start" \| "center" \| "end"`	`"start"`
`sideOffset` Odstęp od kursora w px.	`number`	`0`
`alignOffset` Przesunięcie wzdłuż osi wyrównania w px.	`number`	`4`

ContextMenuItem

Prop	Typ	Domyślnie
`variant` Pozycje destrukcyjne mają kolor danger.	`"default" \| "destructive"`	`"default"`
`inset` Dodaje odstęp na początku, żeby wyrównać pozycję z pozycjami, które mają ikony.	`boolean`	`false`
`onClick` Wywoływana po aktywowaniu pozycji.	`(event) => void`	Brak wartości domyślnej
`closeOnClick` Czy aktywowanie pozycji zamyka menu.	`boolean`	`true`
`disabled` Pomija pozycję i ignoruje kliknięcia.	`boolean`	`false`
`label` Tekst do wyszukiwania przez wpisywanie, gdy treść pozycji nie jest zwykłym tekstem.	`string`	Brak wartości domyślnej

Pozostałe części

ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, ContextMenuLabel, ContextMenuSeparator, ContextMenuShortcut i ContextMenuGroup mają takie samo API jak odpowiadające im części Dropdown Menu.