Context Menu

Displays a menu of actions triggered by a right click.

Overview

在虚线框里右键 —— 菜单在指针处弹出，点击外部或 Escape 关闭。

GPUI · Live previewGPUI WASM

Installation

Context Menu 是单个 Rust 文件（src/context_menu.rs）—— 浮层走 deferred() overlay pass，键盘导航用 FocusHandle + on_key_down，图标和 ⌘/⇧/⌥/⌃ 修饰键全部 PathBuilder 手绘（Geist 没有这些码位）。

Cargo.toml

1[dependencies]2gpui-kit = "0.6.6"34# context_menu.rs is self-contained: FocusHandle for keyboard5# nav, deferred() for the popup pass, PathBuilder glyphs — no6# extra deps.

Download runnable example

Terminal

1# Download the runnable example crate, then:2cargo run --locked -- --context-menu34# Other demos:5cargo run --locked -- --context-menu submenu6cargo run --locked -- --context-menu selection7cargo run --locked -- --context-menu destructive

Usage

ContextMenu 是实体：.trigger(..) 接收一个元素工厂作为右键区域，菜单项用 ContextMenuEntry 枚举声明（Item / Label / Separator）。右键在指针处弹出，点击行发出 ContextMenuSelectEvent。

Example.rs

1use justdo_command::context_menu::{2    ContextMenu, ContextMenuEntry, ContextMenuItem, ContextMenuSelectEvent,3};45let menu = cx.new(|cx| {6    ContextMenu::new(7        // Trigger area — any renderable element factory.8        move || {9            div()10                .p_4()11                .border_1()12                .border_dashed()13                .child("Right click here")14                .into_any_element()15        },16        vec![17            ContextMenuEntry::Item(ContextMenuItem::new("Profile")),18            ContextMenuEntry::Item(ContextMenuItem::new("Billing")),19            ContextMenuEntry::Item(20                ContextMenuItem::new("Settings").shortcut("⌘S"),21            ),22            ContextMenuEntry::Separator,23            ContextMenuEntry::Item(24                ContextMenuItem::new("Delete").destructive(true),25            ),26        ],27        cx,28    )29});3031cx.subscribe(&menu, |view, _, ev: &ContextMenuSelectEvent, cx| {32    view.handle(ev.value.clone());33    cx.notify();34});3536div().size_full().child(menu)

网页预览与桌面端运行同一份 Rust / GPUI 组件。

Composition

结构对应 ContextMenuTrigger + ContextMenuContent → Item / Label / Separator / Sub / CheckboxItem / RadioItem / Shortcut。子菜单用 .submenu(vec![...]) 内嵌，复选与单选行提交后菜单保持打开。

Structure

1ContextMenu                entity — trigger + popup + nav state2├── ContextMenuTrigger    .trigger(factory) — right-click surface3│                         (secondary-button MouseDown → open at pointer)4├── ContextMenuContent    floating panel — deferred pass, viewport-clamped5│   ├── ContextMenuGroup  ContextMenuEntry::Label — muted heading6│   ├── ContextMenuItem   icon + label + shortcut + ▸7│   │                     .value(..) .icon(..) .shortcut(..)8│   │                     .disabled(..) .destructive(..)9│   ├── ContextMenuCheckboxItem   .checkbox(bool) — stays open on toggle10│   ├── ContextMenuRadioItem      .radio("group") — exclusive per group11│   ├── ContextMenuSeparator      ContextMenuEntry::Separator12│   └── ContextMenuSub    ContextMenuItem::submenu(vec![...])13│         └── SubContent  second panel at the trigger row14└── emits                 ContextMenuSelectEvent { value, checked, group }

Positioning.rs

1// Pointer coordinates arrive in window space; the component2// captures its root bounds each prepaint and converts to local3// space, so the menu anchors correctly wherever the trigger4// sits. Panels clamp inside the root bounds (MENU_W = 208px).5//6// Right-clicking elsewhere while open re-anchors the menu —7// same as the OS menu.

Keyboard

菜单打开时焦点移到浮层：↑/↓ 移动高亮（跳过禁用行），→ 打开子菜单，← 收起子菜单，Enter 执行，Escape 关闭。鼠标 hover 同样驱动高亮与子菜单开合。

Key handling.rs

1// When the menu opens, a FocusHandle on the overlay takes2// keyboard focus:3//4//   ↑ / ↓    move the active row (disabled rows are skipped)5//   →        open the submenu under the active row6//   ←        close the submenu (or the menu)7//   Enter    activate the active row8//   Escape   close9//10// Hovering a row also moves the highlight and opens its11// submenu, mirroring OS menus.

Accessibility

Semantics

禁用行半透明且不进入高亮序列；destructive 项红色双重标识；checkbox 行渲染 ✓、radio 行渲染圆点，状态可从实体读取（checked(..) / radio_value(..)）。

Dismissal

点击外部 / Escape / 选择普通项关闭；右键点击别处把菜单重新锚定到新的指针位置，与系统菜单一致。

API Reference

实体暴露的构造器、builder 方法与事件。

API	Signature	Notes
`ContextMenu::new(..)`	`trigger factory, Vec<ContextMenuEntry>`	Trigger renders via a factory closure.
`ContextMenuItem::new(..)`	`&str label`	`.value(..)` `.icon(..)` `.shortcut(..)` `.disabled(..)` `.destructive(..)`
`.checkbox(..)`	`bool`	Toggle row; menu stays open.
`.radio(..)`	`&str group`	Exclusive within the group.
`.submenu(..)`	`Vec<ContextMenuEntry>`	Nested panel (one level deep).
`.set_open(..)`	`bool, Window, cx`	Controlled open at trigger center.
`.checked(..)`	`-> Option<bool>`	Checkbox state by value.
`.radio_value(..)`	`-> Option<SharedString>`	Current value of a radio group.
`ContextMenuSelectEvent`	`{ value, checked, group }`	Emitted on every activation.

Source & inspiration

结构与交互参考 shadcn/ui Context Menu (React Aria) 。本页交互由 Rust / GPUI 绘制，基础原语来自 gpui-kit 。