068 CommandPalette 命令面板

用途

用快捷键（默认 Cmd+K，非 macOS 为 Ctrl+K）打开的模态命令搜索框：输入过滤、分组显示、无结果提示、方向键选择，执行后关闭。

最小示例

res := navigation.CommandPalette(c, &open, []navigation.Command{
	{ID: "new", Label: "New document", Group: "File"},
	{ID: "theme", Label: "Toggle dark mode", Group: "View", Keywords: []string{"night"}},
}, navigation.CommandPaletteOptions{})
if id, ok := res.Chosen(); ok {
	fmt.Println("run", id)
}

签名：func CommandPalette(c *ui.Context, open *bool, commands []Command, opts CommandPaletteOptions) CommandPaletteResult

参数

open：是否显示；快捷键把它设为 true，执行、Escape 或点击遮罩设为 false。调用方也可直接设置。

Command

字段	类型	默认值	含义
`ID`	`string`	必填	`Chosen` 报告的标识；为空或重复时 panic。
`Label`	`string`	必填	显示名称；为空时 panic。
`Group`	`string`	""	分组标题；分组按首次出现的顺序排列，组内保持原顺序。
`Keywords`	`[]string`	nil	额外的搜索词。
`Icon`	`*ui.SVG`	nil	名称前图标。

CommandPaletteOptions

字段	类型	默认值	含义
`OpenMods`	`ui.Modifiers`	0	打开快捷键的修饰键。
`OpenKey`	`ui.Key`	0（即 `ui.Cmd`+K）	打开快捷键；为 0 时忽略 `OpenMods`。

返回 CommandPaletteResult；关闭时其 Element 为 nil。

状态

打开：遮罩变暗，面板在窗口上部，焦点在搜索框；每次打开都清空搜索。
搜索：不区分大小写，按空格分词，每个词须出现在名称、分组或关键词中。
高亮项：Selection 背景、左侧 AccentText 边线、600 字重；键盘移动时滚入视野。
无结果：显示“没有匹配的命令”，Enter 不执行任何命令。
底部提示栏说明 ↑↓、Enter、Esc。

事件

Chosen() (string, bool)：本帧执行的命令 ID（Enter 或点击），同时关闭面板。

键盘操作

Cmd+K / Ctrl+K：打开（窗口级快捷键）。
输入：过滤。↑/↓：移动高亮并循环。Enter：执行并关闭。Escape：关闭不执行，焦点回到打开前的元素。
Tab 限制在面板内（MyGo 模态对话框行为）。

限制

操作说明放在底部提示栏而不放进输入框，避免与输入法组合文字重叠；搜索框以无障碍名称“搜索命令”标识。
搜索是子串匹配，不做模糊匹配或排序打分。
焦点留在搜索框以便继续输入；方向键移动高亮时用 c.Announce 朗读当前命令，并写入搜索框的 Description（MyGo 的 active descendant 不公开）。
弹层打开时在 160 ms 内淡入，减少动画时直接显示。关闭时立即消失：弹层关闭后 MyGo 不再构建其元素，公开接口无法为已移除的浮层做淡出。
搜索内容变化后高亮回到第一项，并滚入视野。