组件
ShadcnCommand
命令面板(⌘K):输入过滤 + 键盘上下选择 + 分组。

命令面板。对齐 shadcn v4 base-nova 的 command(基于 cmdk 的交互模型)。
关键设计:声明式,不是 model 驱动。 官方 cmdk 是声明式 DOM 树过滤 ——
CommandItem 写在哪就在哪,过滤只是把不匹配的隐藏。Qt 侧保持同样语义:
组合出 CommandGroup / CommandItem / CommandSeparator,过滤时隐藏不匹配项
并让选中索引跳过它们。model 化会丢掉「分组 + 分隔线 + 图标 + 快捷键」的组合
表达力,而这些正是这组件的形态本身。
用法
// 官方唯一形态:套在 Dialog 里,⌘K 呼出
Shortcut {
sequence: "Ctrl+K" // macOS 可用 "Meta+K"
onActivated: palette.open()
}
ShadcnCommandDialog {
id: palette
ShadcnCommandInput { placeholderText: qsTr("输入命令或搜索...") }
ShadcnCommandList {
ShadcnCommandEmpty { text: qsTr("没有匹配结果") }
ShadcnCommandGroup {
heading: qsTr("建议")
ShadcnCommandItem {
text: qsTr("日历")
iconName: "calendar"
onActivated: console.log("calendar")
}
ShadcnCommandItem {
text: qsTr("搜索邮件")
iconName: "search"
shortcut: "⌘F"
}
}
ShadcnCommandSeparator {}
ShadcnCommandGroup {
heading: qsTr("设置")
ShadcnCommandItem { text: qsTr("外观"); iconName: "palette" }
}
}
}
组件
| 组件 | 说明 |
|---|---|
ShadcnCommand | 根容器。管理查询串、过滤、选中项、键盘导航 |
ShadcnCommandDialog | 官方形态:ShadcnDialog 的薄封装,内容区 p-0 + top-1/3 |
ShadcnCommandInput | 搜索框(ShadcnInput + 前置搜索图标)。输入即过滤 |
ShadcnCommandList | 可滚动列表,max-h-72(288px) |
ShadcnCommandGroup | 分组,带 heading(text-xs + mutedForeground) |
ShadcnCommandItem | 命令项。选中 bg-muted;iconName / shortcut / enabled |
ShadcnCommandEmpty | 无匹配时的占位(py-6 text-center) |
ShadcnCommandSeparator | 分隔线(h-px + theme.border) |
ShadcnCommandShortcut | 右侧快捷键提示(text-xs tracking-widest mutedForeground) |
ShadcnCommand 属性
| 属性 | 默认 | 说明 |
|---|---|---|
search | "" | 当前查询串,由 Input 双向绑定 |
matchCount | — | 只读,匹配到的项数 |
value | — | 只读,当前选中项的匹配值 |
activeItem | — | 只读,当前选中项 |
shouldFilter | true | 关掉则自行过滤(配合 filter) |
filter | null | 自定义过滤函数 (query, text) => bool,默认走 C++ CommandFilter |
loop | false | ↑↓ 到边界后是否环绕 |
inDialog | false | 由 ShadcnCommandDialog 自动置位,控制样式微调 |
信号:activated(string value) 回车或点击某项时发出;selectedValueChanged(string value) 选中项变化。
过滤
默认过滤在 C++ 侧(src/core/commandfilter.cpp)实现,有独立单测
(tests/core/commandfilter_test.cpp)。规则对齐 cmdk:
- 大小写不敏感
- 子串匹配 + 字符顺序匹配(
gcl能匹配到Google Chrome) - 空查询 → 全部显示
- 中文直接子串匹配(不做拼音转换,避免过度设计)
通过 filter 属性可替换成自己的实现。
键盘
| 键 | 行为 |
|---|---|
↑ / ↓ | 移动选中项,跳过被过滤掉和禁用的项 |
Enter | 执行当前选中项,发 activated(value) |
Esc | 关闭(由外层 Dialog 处理) |
Tab | 不进列表(焦点留在 Input) |
边界:全局快捷键归宿主
组件不注册任何全局快捷键。⌘K 是应用级决定(面板可能不止一个、键位可能被改、
也可能要占用别的组合键),所以由宿主用 Shortcut 挂到 Window/Page 上再调用
open()。showcase 演示页给出了完整写法。
已知偏差
- 不做虚拟滚动:命令面板的条目量通常在几十条以内,
ListView足够;上千条 的场景应该改用过滤而不是滚动。 CommandDialog没有独立的关闭钮:与官方一致(showCloseButton=false), Esc 或执行某项后关闭。
