QtShadcn
组件

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—只读,当前选中项
shouldFiltertrue关掉则自行过滤(配合 filter)
filternull自定义过滤函数 (query, text) => bool,默认走 C++ CommandFilter
loopfalse↑↓ 到边界后是否环绕
inDialogfalse由 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 或执行某项后关闭。
Copyright © 2026