67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# 068 CommandPalette 命令面板
|
||
|
||
## 用途
|
||
|
||
用快捷键（默认 Cmd+K，非 macOS 为 Ctrl+K）打开的模态命令搜索框：输入过滤、分组显示、无结果提示、方向键选择，执行后关闭。
|
||
|
||
## 最小示例
|
||
|
||
```go
|
||
res := mujica.CommandPalette(c, &open, []mujica.Command{
|
||
{ID: "new", Label: "New document", Group: "File"},
|
||
{ID: "theme", Label: "Toggle dark mode", Group: "View", Keywords: []string{"night"}},
|
||
}, mujica.CommandPaletteOptions{})
|
||
if id, ok := res.Chosen(); ok {
|
||
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 模态对话框行为）。
|
||
|
||
## 限制
|
||
|
||
- MyGo `TextInputBase` 没有占位文字（`ui/editor.go:734`）；为避免与输入法组合文字重叠，说明放在底部提示栏，搜索框以无障碍名称“搜索命令”标识。
|
||
- 搜索是子串匹配，不做模糊匹配或排序打分。
|
||
- 焦点留在搜索框以便继续输入；方向键移动高亮时用 `c.Announce` 朗读当前命令，并写入搜索框的 `Description`（MyGo 的 active descendant 不公开）。
|