Menu
Example sourceGo · Copyable
This is the complete source for the gallery example above.examples/components/menu.go
Reuse the component construction and Render methods in a scaffolded project. The example’s registerSection and shared helpers are provided by the component gallery.
package main
import (
"fmt"
"image"
"image/color"
"time"
"github.com/dyike/keel/ui/core"
"github.com/dyike/keel/ui/el"
"github.com/dyike/keel/ui/kit"
"github.com/dyike/keel/ui/theme"
"github.com/dyike/keel/ui/window"
)
func init() {
registerSection("menu", "overlays", func() core.Widget { return el.Root(newMenuGallery()) })
}
type menuGallery struct {
menu *kit.MenuView
long, context *kit.MenuView
last string
native *window.MenuBar
preview *window.Window
animated bool
}
func newMenuGallery() *menuGallery {
g := &menuGallery{last: demoText("Nothing selected", "尚未选择")}
if err := core.Bind("gallery.menu.inspect", "f7"); err != nil {
panic(err)
}
if err := core.BindIn("menu-gallery", "gallery.menu.inspect", "f6"); err != nil {
panic(err)
}
do := func(s string) func() { return func() { g.last = demoText("Executed: ", "已执行:") + s } }
export := kit.Menu().Item(demoText("PDF document", "PDF 文档"), "", do(demoText("Export PDF", "导出 PDF"))).Item(demoText("CSV spreadsheet", "CSV 表格"), "", do(demoText("Export CSV", "导出 CSV")))
g.menu = kit.Menu().Label(demoText("Editing actions", "编辑操作")).
IconItem(demoText("Copy", "复制"), "mod+c", kit.IconCopy, do(demoText("Copy", "复制"))).
Item(demoText("Paste", "粘贴"), "mod+v", do(demoText("Paste", "粘贴"))).
Item(demoText("Undo 123", "撤销 123"), "mod+z", do(demoText("Undo", "撤销"))).
Separator().
Label(demoText("File actions", "文件操作")).Sub(demoText("Export", "导出"), export).
Item(demoText("Delete", "删除"), "delete", do(demoText("Delete", "删除"))).
CheckItem(demoText("Show details", "显示详情"), "", true, func(on bool) { g.last = fmt.Sprintf(demoText("Show details: %v", "显示详情:%v"), on) })
g.menu.ContentItem(demoText("Project details", "项目详情"), "", el.ViewFunc(func(cx *el.Context) el.Element {
return el.Div().Gap(theme.SpaceXs).Child(el.Text(demoText("Project details", "项目详情")).Bold(), el.Text(demoText("View project status and recent activity", "查看项目状态与最近活动")).TextSize(theme.TextSm).TextColor(theme.Muted))
}), do(demoText("Project details", "项目详情")))
g.menu.ActionItem(demoText("Context command", "上下文命令"), "gallery.menu.inspect", do(demoText("Context command", "上下文命令")))
g.menu.Link(demoText("Keel documentation", "Keel 文档"), "https://github.com/dyike/keel")
g.menu.SetItemDisabled(demoText("Paste", "粘贴"), true)
g.menu.Trigger(kit.Button(demoText("More actions", "更多操作"), g.menu.Toggle).Variant(kit.ButtonSecondary))
g.long = kit.Menu().Scrollbars(el.ScrollbarAlways)
for i := 1; i <= 60; i++ {
label := fmt.Sprintf(demoText("Action %02d", "操作 %02d"), i)
g.long.Item(label, "", do(label))
}
g.long.Trigger(kit.Button(demoText("Long menu: try End / Home", "长菜单:试试 End / Home"), g.long.Toggle))
g.context = kit.Menu().Item(demoText("Copy selection", "复制选区"), "", do(demoText("Copy selection", "复制选区"))).Item(demoText("View details", "查看详情"), "", do(demoText("View details", "查看详情")))
g.context.Trigger(el.ViewFunc(func(*el.Context) el.Element {
return el.Div().Role("button").Name(demoText("Context menu region", "右键菜单区域")).Focusable(true).P(16).Bg(theme.Subtle).OnContextMenu(g.context.Toggle).OnKey(func(e el.KeyEvent) bool {
if e.Name == "F10" {
if e.State == el.KeyPress {
g.context.Toggle()
}
return true
}
return false
}).Child(el.Text(demoText("Right-click here, or focus and press F10", "在这里右键,或聚焦后按 F10")))
}))
return g
}
func (g *menuGallery) Render(cx *el.Context) el.Element {
cx.ActionAt("menu-gallery", "gallery.menu.inspect", func() { g.last = demoText("Executed: context command", "已执行:上下文命令") })
return el.Div().ID("menu-gallery").KeyContext("menu-gallery").ScrollY().P(24).Gap(12).Items(el.Start).Child(
el.Text(demoText("Menu: ↑ ↓ moves; → opens a submenu; ← or Esc goes back.", "Menu:↑ ↓ 移动,→ 打开子菜单,← / Esc 返回")).Bold(),
el.Text(demoText("Context commands in this region use F6; the global default is F7", "本区域的上下文命令使用 F6;全局默认是 F7")).TextColor(theme.Muted),
g.menu.Render(cx),
g.long.Render(cx), g.context.Render(cx),
el.Text(g.last).TextColor(theme.Muted),
el.Text(demoText("Application menus: icons and platform animation controls", "应用菜单:图标与平台动画控制")).Bold(),
kit.Button(demoText("Install native menu with icons", "安装带图标的原生菜单"), g.installNativeMenu).Render(cx),
kit.Button(demoText("Preview animated window menu", "预览窗口菜单动画"), g.previewMenu).Render(cx),
kit.Button(demoText("Toggle window menu animation", "切换窗口菜单动画"), func() {
g.installNativeMenu()
g.animated = !g.animated
animation := window.MenuAnimation{}
if g.animated {
animation = window.MenuAnimation{Duration: 180 * time.Millisecond, Offset: 6}
}
if err := g.native.SetWindowAnimation(animation); err != nil {
panic(err)
}
g.last = fmt.Sprintf(demoText("Window menu animation: %v", "窗口菜单动画:%v"), g.animated)
}).Render(cx),
el.Text(demoText("Native opening follows the OS; window animation respects reduced motion.", "原生展开动画跟随系统;窗口菜单动画遵守减弱动画设置。")).TextColor(theme.Muted),
)
}
func (g *menuGallery) installNativeMenu() {
if g.native == nil {
art := image.NewNRGBA(image.Rect(0, 0, 32, 32))
for y := 6; y < 26; y++ {
for x := 6; x < 26; x++ {
if x < 10 || y < 10 || y > 21 {
art.SetNRGBA(x, y, color.NRGBA{R: 75, G: 130, B: 240, A: 255})
}
}
}
mask, err := window.NewMenuIcon(art, true)
if err != nil {
panic(err)
}
colored, err := window.NewMenuIcon(art, false)
if err != nil {
panic(err)
}
g.native, err = window.NewMenuBar(window.MenuItem{ID: "gallery-native", Title: demoText("Keel Menu", "Keel 菜单"), Children: []window.MenuItem{
{ID: "native-action", Title: demoText("Action with icon", "带图标的操作"), Icon: mask, OnSelect: func() { g.last = demoText("Executed: native icon action", "已执行:原生图标操作") }},
{ID: "native-check", Title: demoText("Checked icon", "勾选图标"), Checked: true, Icon: colored, OnSelect: func() {
if err := g.native.UpdateItem("native-check", func(item *window.MenuItem) { item.Checked = !item.Checked }); err != nil {
panic(err)
}
}},
{Title: demoText("Unavailable icon", "禁用图标"), Disabled: true, Icon: mask},
{Separator: true},
{Title: demoText("Nested icons", "嵌套图标"), Icon: colored, Children: []window.MenuItem{{Title: demoText("Child action", "子菜单操作"), Icon: mask, OnSelect: func() { g.last = demoText("Executed: child icon action", "已执行:子菜单图标操作") }}}},
}})
if err != nil {
panic(err)
}
g.animated = true
if err := g.native.SetWindowAnimation(window.MenuAnimation{Duration: 180 * time.Millisecond, Offset: 6}); err != nil {
panic(err)
}
}
if err := g.native.Install(); err != nil {
panic(err)
}
}
func (g *menuGallery) previewMenu() {
g.installNativeMenu()
if g.preview != nil && !g.preview.Closed() {
g.preview.Raise()
return
}
g.preview = window.Open(window.Options{
Title: demoText("Menu icons and animation", "菜单图标与动画"), Width: 520, Height: 300, MenuDisplay: window.MenuDisplayWindow,
Content: el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
return el.Div().Gap(16).Child(
el.Text(demoText("Open Keel Menu or press F10 to inspect the icons.", "打开 Keel 菜单或按 F10 查看图标。")),
el.Text(g.last),
kit.Button(demoText("Cancel menu tracking", "取消菜单跟踪"), func() { g.native.CancelTracking(false) }).Render(cx),
)
})),
OnClose: func() { g.preview = nil },
})
}
A menu of commands that pops up next to the triggering element.
export := kit.Menu().Item("PDF", "", exportPDF).Item("CSV", "", exportCSV)
more := kit.Menu().
Item("Copy", "mod+c", copy).
Separator().
Sub("Export", export).
Item("Delete", "delete", remove)
more.SetItemDisabled("Copy", !hasSelection)
more.Trigger(kit.Button("More", more.Toggle).Variant(kit.ButtonGhost))
Item(label, shortcut, action):shortcutuses the writing method ofcore.ParseShortcut, only useskit.Kbdto display, does not register the shortcut key; pass an empty string when not needed.Sub(label, menu)adds a submenu,Separator()adds a divider, andSetItemDisabled(label, bool)disables or enables menu items.- The menu is modal: the rest of the page does not respond to clicks when opened, focus is limited to the menu, and when opened it focuses on the first available item. Click outside or press Esc to close. After closing, the focus returns to the triggering element.
- keyboard:
- ↑ ↓ Move between available items, skip disabled items and separators, and loop from beginning to end;
- Home / End Jump to the first or last item;
- Enter / Space executes the current item;
- → Open the submenu, ← or Esc only close the current submenu.
- After executing any of the items, the entire menu (including all submenus) is closed before the action is called.
- The submenu is displayed on the right side by default and flips to the left if it cannot fit.
Value()/SetValue(bool)reads or sets whether to open,Toggleis used as a click callback to trigger the element, andWidth(dp)sets the minimum width (default 220).
Agent: The role of the menu container is menu (the name of the submenu is its title in the parent menu), the role of the menu item is menuitem; items with submenus value are submenu; disabled items report disabled.
Verification: go run ./examples/components -section menu.
Long menus are constrained to the window and scroll vertically. The arrow keys and Home / End will scroll the target item into the visible range; if the previous items are disabled when opening, the first available item will also be displayed. When the width is too large, it is constrained by the window width.
SetDisabled(true) Closes and disables the entire menu; disabling the expanding parent or submenu closes the corresponding branch. The expanded state is cleared recursively when closing the top level, and reopening does not restore the old deep submenus. Sub ignores nil, circular references and repeatedly mounted submenu instances; please create separate instances for different branches.
For right-click triggering, you can pass a custom View to Trigger and call Toggle in OnContextMenu of the element. The keyboard entrance is defined by the OnKey of the triggering View. The example uses F10; the elastic layer is still anchored to the trigger area, and the closing behavior of external clicks and Esc is the same.
Placement(side, align) Sets the top menu direction (Top/Bottom/Left/Right) and alignment (Start/Center/End), defaults to Bottom/Start; illegal combinations are ignored. Offset(dp) sets the spacing, the default is 4dp, supports 0 and negative value overlap, and non-finite values are ignored. It can be updated while it is open. When there is insufficient space, overlay flipping and in-window restrictions will be used. The submenu is still expanded by Right/Start, 2dp.
These two methods of DropdownButton directly configure the incoming Menu; normal mode anchors the whole button, and split mode anchors the arrow. Callers that share the same Menu will also see configuration changes.
IconItem(label, shortcut, icon, action) adds the icon command, SetItemIcon(label, icon) can update the icons of ordinary items, check items or submenu entries; IconNone is removed. Menus with prefixed tags uniformly reserve the tag column, and the text remains aligned.
CheckItem(label, shortcut, checked, onChange) Add check option. Click /Enter/Space to switch the internal state, close the entire menu chain, and then call onChange(bool); disabled items are not switched. SetItemChecked(label, checked) does not trigger a callback; ItemChecked(label) returns status and whether it is found. The update method applies to all items with the same name in the current menu. The query returns the first matching item. It is recommended to use a unique label.
CheckSide(el.Left/Right) sets the check mark position of the current menu; by default, the left side replaces the item icon, and the right side can display the icon at the same time. Unknown directions are ignored, and submenus are configured separately. The role in the Agent is menuitemcheckbox and reports the checked status.
Label(text) Inserts a non-interactive group title. Empty text is ignored. The title uses a secondary color and a smaller bold font, has a fixed line height of 30dp, and long text is truncated in a single line; it does not respond to clicks, and will not be the target of arrow keys, Home/End or text search. Long menu positioning counts towards title height. The heading's Agent role is heading; it is just a visual section heading and does not create independent submenus or nested groups.
ContentItem(label, shortcut, content, action) Add custom content lines, which can combine multi-line text, descriptions, icons and other display elements; do not nest buttons/input boxes. label remains an accessible name and text search basis. Clicks and Enter/Space in the entire row execute the same action and close the menu chain.
SetItemContent(label, content) can replace the display content of the common item, check item or submenu entry of the current menu with the same name; nil restores the text. The row identity remains unchanged, and disabled, checked, shortcut keys, and submenu arrows retain the original configuration. The minimum height of the custom row is 30dp, which increases according to the content; the long menu is positioned according to the actual layout height, and the keyboard focus is transferred after scrolling to the visible position.
Link(label, url) adds a link item, retains the menuitem role, and the semantic value is the URL; after clicking or typing with the keyboard, first close the entire menu chain, and then open the link. By default the platform browser/mail handler is called via core.OpenURL, which only accepts absolute HTTP, HTTPS and mailto URLs. SetItemIcon can add the front icon, and ExternalLinkIcon(false) can hide the external link icon on the right.
OnLink(func(string)) can take over the opening behavior and URL strategy. The submenu uses its own callback first, otherwise it looks along the parent menu. By default, OnLinkError(func(error)) notification is used when opening fails, and the search is also performed along the parent menu; errors are ignored when not configured. The default entry only reports a checksum process startup error and does not indicate that the web page is loaded successfully. Web uses window.open, which is restricted by browser pop-up policy.
Show shortcut keys by target area
ActionItem The key is resolved based on the trigger's KeyContext ancestor, and the submenu inherits the top-level target. You can also use ActionContext("editor") to specify an element ID to display the key position of the area where the element is located; no prompt will be displayed when the specified target does not exist, is hidden, or is disabled. An empty string restores the trigger target. The prompt is generated after the current frame is constructed and before measurement, so there is no need to wait for one more frame when opening for the first time or switching contexts in the same frame.
core.Bind("save", "mod+s")
core.BindIn("editor", "save", "mod+shift+s")
menu := kit.Menu().ActionContext("document").ActionItem("Save", "save", save)
// In Render:
cx.ActionAt("document", "save", save)
return el.Div().ID("document").KeyContext("editor").Child(input.Render(cx), menu.Render(cx))
core.BindIn Sets area coverage for an action. The order of priority is inner layer, outer layer, and global. Not passing the key bit means disabling the binding of the action in this area; ClearBindingIn deletes the override and restores inheritance. Invalid key positions will not change the original binding, and changing the binding will require all windows to be refreshed. Keymap/LoadKeymap still only reads and writes global bindings, regional bindings are configured by the application.
Context conditional expression
The first parameter of BindIn can be a conditional expression, which is consistent with the GPUI keymap writing method:
core.BindIn("Editor && !ReadOnly", "format", "mod+shift+f") // editable editor
core.BindIn("Pane > Editor", "close", "mod+w") // Editor in panel
core.BindIn("Terminal || Shell", "clear", "mod+k") // one of the two
- Each level on the focus path is a
el.KeyContext, and the name can contain multiple identifiers separated by spaces, such asKeyContext("Editor ReadOnly"). - Identifies the layer that checks the current matching;
a > bmeans that this layer satisfies b and an outer layer satisfies a. Priority from high to low:!,>,&&,||, grouped by brackets. - When parsing, looking from the innermost layer to the outside, the first layer with established binding will win; when there are multiple establishments in the same layer, the later binding will take effect. If neither is true, use global binding.
- The incorrectly written expression
BindInreturns an error and changes nothing. A single name is an expression with only one identifier, and the original writing method still takes effect.
cx.ActionAt Handles resolved keystrokes only when there is focus within the specified element. Among nested targets, deeper targets take precedence, and the same level is in the order of declaration; explicit null binding in the inner level will also prevent the same action in the outer level from being processed. Do not simultaneously register the same action with global cx.Action. When a function is passed to ActionItem, the click only calls this function; when nil is passed, the click is routed according to the action name: from the trigger (or the element specified by ActionContext), look out for the innermost cx.ActionAt processor. If the global processor of cx.Action cannot be found, the effect is the same as pressing the shortcut key there, and there is no need to bind any keys. In this way, menus, shortcut keys and command panels can be implemented using one command. Routing does not switch focus. The bottom layer is cx.Perform(targetID, action), and the command panel can also be called directly. Explicit shortcut keys for normal Item and standalone KbdFor retain their original behavior. The underlying el.KeyHint can be used to display content with the same rules and is not responsible for registering shortcut keys.
Scrollbar visibility
Use kit.Menu().Scrollbars(el.ScrollbarAlways) to keep the scrollbar visible
whenever the menu overflows. Other modes are ScrollbarHover (pointer inside
or dragging), ScrollbarScrolling (during scrolling and briefly afterward),
and ScrollbarSystem (platform preference). Without an explicit setting,
the global el.SetScrollbarDefault applies. Submenus inherit the nearest
parent's explicit mode and can override it. Invalid values are ignored.
Short menus have symmetric row margins; overflowing menus reserve a scrollbar
hit area even while the bar fades out, so rows do not jump during scrolling.
The long-menu component example uses ScrollbarAlways.