Menu
示例代码Go · 可复制
这是上方组件库展示案例的完整源码。examples/components/menu.go
在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。
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 },
})
}
命令菜单,从触发元素旁边弹出。
export := kit.Menu().Item("PDF", "", exportPDF).Item("CSV", "", exportCSV)
more := kit.Menu().
Item("复制", "mod+c", copy).
Separator().
Sub("导出", export).
Item("删除", "delete", remove)
more.SetItemDisabled("复制", !hasSelection)
more.Trigger(kit.Button("更多", more.Toggle).Variant(kit.ButtonGhost))
Item(label, shortcut, action):shortcut使用core.ParseShortcut的写法,只用kit.Kbd显示,不注册快捷键;不需要时传空字符串。Sub(label, menu)添加子菜单,Separator()添加分隔线,SetItemDisabled(label, bool)禁用或启用菜单项。- 菜单是模态的:打开时页面的其余部分不响应点击,焦点限制在菜单内,打开后聚焦第一个可用项。点击外部或按 Esc 关闭,关闭后焦点回到触发元素。
- 键盘:
- ↑ ↓ 在可用项之间移动,跳过禁用项和分隔线,首尾循环;
- Home / End 跳到第一项或最后一项;
- Enter / Space 执行当前项;
- → 打开子菜单,← 或 Esc 只关闭当前这一层子菜单。
- 执行任意一项后,整个菜单(包括所有子菜单)都会关闭,然后再调用 action。
- 子菜单默认显示在右侧,放不下时翻到左侧。
Value()/SetValue(bool)读取或设置是否打开,Toggle用作触发元素的点击回调,Width(dp)设置最小宽度(默认 220)。
Agent:菜单容器的角色是 menu(子菜单的名字是它在父菜单中的标题),菜单项的角色是 menuitem;有子菜单的项 value 为 submenu;禁用的项报告 disabled。
验证:go run ./examples/components -section menu。
长菜单会限制在窗口内并纵向滚动。方向键、Home / End 会把目标项滚入可见范围;打开时若前面多项禁用,也会显示第一个可用项。宽度过大时受窗口宽度约束。
SetDisabled(true) 关闭并禁用整个菜单;禁用正在展开的父项或子菜单会关闭对应分支。关闭顶层时会递归清除展开状态,重新打开不会恢复旧的深层子菜单。Sub 忽略 nil、循环引用和重复挂载的子菜单实例;不同分支请分别创建实例。
右键触发可以给 Trigger 传入自定义 View,在元素的 OnContextMenu 中调用 Toggle。键盘入口由触发 View 的 OnKey 定义,示例使用 F10;弹层依然锚定触发区域,外部点击和 Esc 的关闭行为相同。
Placement(side, align) 设置顶层菜单方向(Top/Bottom/Left/Right)和对齐(Start/Center/End),默认 Bottom/Start;非法组合忽略。Offset(dp) 设置间距,默认 4dp,支持 0 和负值重叠,非有限值忽略。打开期间可更新,空间不足时沿用浮层翻转和窗口内限制。子菜单仍按 Right/Start、2dp 展开。
DropdownButton 的这两个方法直接配置传入的 Menu;普通模式锚定整按钮,分体模式锚定箭头。共用同一 Menu 的调用方也会看到配置变化。
IconItem(label, shortcut, icon, action) 添加图标命令,SetItemIcon(label, icon) 可更新普通项、勾选项或子菜单入口的图标;IconNone 移除。含前置标记的菜单统一预留标记列,文字保持对齐。
CheckItem(label, shortcut, checked, onChange) 添加勾选项。点击/Enter/Space 切换内部状态,关闭整个菜单链,再调用 onChange(bool);禁用项不切换。SetItemChecked(label, checked) 不触发回调;ItemChecked(label) 返回状态和是否找到。更新方法作用于当前菜单中所有同名项,查询返回首个匹配项,建议使用唯一标签。
CheckSide(el.Left/Right) 设置当前菜单的勾号位置;默认左侧替代该项图标,右侧可同时显示图标。未知方向忽略,子菜单单独配置。Agent 中角色为 menuitemcheckbox,并报告 checked 状态。
Label(text) 插入不可交互的分组标题,空文字忽略。标题使用次级色和较小的粗体字,固定占 30dp 行高,长文字单行截断;不响应点击,也不会成为方向键、Home/End 或文字搜索的目标。长菜单定位计入标题高度。标题的 Agent 角色为 heading;它只是视觉分节标题,不创建独立子菜单或嵌套 group。
ContentItem(label, shortcut, content, action) 添加自定义内容行,可组合多行文字、说明、图标等展示元素;不要嵌套按钮/输入框。label 保留为可访问名称和文字搜索依据。整行点击、Enter/Space 都执行同一个 action,并关闭菜单链。
SetItemContent(label, content) 可替换当前菜单同名普通项、勾选项或子菜单入口的显示内容;nil 恢复文字。行身份保持不变,禁用、勾选、快捷键和子菜单箭头沿用原项配置。自定义行最小高度 30dp,按内容增高;长菜单按实际布局高度定位,滚动到可见位置后才转移键盘焦点。
Link(label, url) 添加链接项,保留 menuitem 角色,语义 value 为 URL;点击或键盘执行后先关闭整条菜单链,再打开链接。默认通过 core.OpenURL 调用平台浏览器/邮件处理程序,仅接受绝对 HTTP、HTTPS 和 mailto URL。SetItemIcon 可添加前置图标,ExternalLinkIcon(false) 隐藏右侧外链图标。
OnLink(func(string)) 可接管打开行为和 URL 策略,子菜单优先使用自己的回调,否则沿父菜单查找。默认打开失败时通过 OnLinkError(func(error)) 通知,同样沿父菜单查找;未配置时忽略错误。默认入口只报告校验和进程启动错误,不表示网页加载成功。Web 使用 window.open,受浏览器弹窗策略限制。
按目标区域显示快捷键
ActionItem 根据触发器的 KeyContext 祖先解析键位,子菜单继承顶层目标。也可以用 ActionContext("editor") 指定一个元素 ID,显示该元素所在区域的键位;指定目标不存在、隐藏或禁用时不显示提示。空字符串恢复触发器目标。提示在当前帧构建完成后、测量之前生成,因此首次打开或同帧切换上下文不需要多等一帧。
core.Bind("save", "mod+s")
core.BindIn("editor", "save", "mod+shift+s")
menu := kit.Menu().ActionContext("document").ActionItem("保存", "save", save)
// Render 中:
cx.ActionAt("document", "save", save)
return el.Div().ID("document").KeyContext("editor").Child(input.Render(cx), menu.Render(cx))
core.BindIn 对一个动作设置区域覆盖,优先顺序为内层、外层、全局。不传键位表示在此区域禁用该动作的绑定;ClearBindingIn 删除覆盖并恢复继承。无效键位不会更改原绑定,改绑会请求所有窗口刷新。Keymap/LoadKeymap 仍只读写全局绑定,区域绑定由应用配置。
上下文条件表达式
BindIn 的第一个参数可以是条件表达式,和 GPUI 的 keymap 写法一致:
core.BindIn("Editor && !ReadOnly", "format", "mod+shift+f") // 可编辑的编辑器
core.BindIn("Pane > Editor", "close", "mod+w") // 面板里的编辑器
core.BindIn("Terminal || Shell", "clear", "mod+k") // 两者之一
- 焦点路径上的每一层是一个
el.KeyContext,名字可以包含多个用空格分隔的标识,如KeyContext("Editor ReadOnly")。 - 标识检查当前匹配的这一层;
a > b表示这一层满足 b、外面某一层满足 a。优先级从高到低:!、>、&&、||,括号分组。 - 解析时从最内层往外找,第一个有绑定成立的层胜出;同一层有多个成立时,后绑定的生效。都不成立时用全局绑定。
- 写错的表达式
BindIn返回错误,什么都不改。单个名称就是只有一个标识的表达式,原来的写法照常生效。
cx.ActionAt 仅在指定元素内有焦点时处理解析出的按键。嵌套目标中,较深的目标优先,同层按声明顺序;内层显式空绑定也会阻止外层同动作处理。不要同时用全局 cx.Action 注册同一动作。ActionItem 传了函数时,点击只调用这个函数;传 nil 时,点击按动作名路由:从触发器(或 ActionContext 指定的元素)往外找最内层的 cx.ActionAt 处理器,找不到再用 cx.Action 的全局处理器,和在那里按快捷键效果一样,而且不需要绑定任何键。这样菜单、快捷键和命令面板可以共用一份命令实现。路由不会切换焦点。底层是 cx.Perform(targetID, action),命令面板等也可以直接调用。普通 Item 的显式快捷键和独立 KbdFor 保持原有行为。底层 el.KeyHint 可用于相同规则的展示内容,不负责注册快捷键。
滚动条显示方式
使用 kit.Menu().Scrollbars(el.ScrollbarAlways),可在菜单内容溢出时始终显示滚动条。
其他模式包括 ScrollbarHover(鼠标位于菜单内或拖动滚动条时显示)、
ScrollbarScrolling(滚动时及停止后短暂显示)和 ScrollbarSystem(跟随系统)。
未设置时使用全局 el.SetScrollbarDefault。子菜单继承最近父菜单的显式配置,
也可以单独覆盖;无效值会被忽略。
短菜单使用左右对称的行边距;溢出的菜单在滚动条淡出后仍保留点击区域,
避免滚动过程中菜单项左右跳动。组件示例中的长菜单使用 ScrollbarAlways。