- 全局唤起的命令面板用
TxCommandPalette;版面内长驻的搜索区用本组件,两者键盘契约一致。 - 用作命令列表时在
select 中执行动作并清空查询;用作筛选器时保留查询。 - 远端搜索传
:filter="items => items" 关闭内建匹配,在 queryChange 中自行防抖取数。 - 同义词放进
keywords;不可用的项设 disabled 置灰,不要从 items 中删除。 - 按最常见的结果数设定
minHeight,过小会重新出现跳动。
| 属性名 | 类型 | 默认值 | 说明 |
|---|
modelValue | string | '' | 查询文本,配合 v-model。 |
items | SearchPanelItem[] | [] | 候选项。 |
placeholder | string | 'Search' | 输入框占位文本。 |
ariaLabel | string | - | 输入框的无障碍名称;缺省时用 placeholder。 |
idleCount | number | 5 | 空查询时显示的条数;0 显示全部。 |
emptyThreshold | number | 3 | 显示空态所需的最短查询长度。 |
emptyTitle | string | 'No results found' | 空态标题。 |
emptyDescription | string | 'Adjust your search to try again' | 空态说明。 |
clearLabel | string | 'Clear search' | 清除按钮的无障碍名称。 |
listLabel | string | 'Search results' | 结果列表的无障碍名称。 |
minHeight | number | string | 248 | 预留高度,结果增减时版面不跳动。 |
filter | (items, query) => items | - | 替换内建匹配:对 label 与 keywords 不区分大小写的 includes。 |
clearable | boolean | true | 显示清除按钮。 |
disabled | boolean | false | 禁用输入。 |
| 事件名 | 载荷 | 说明 |
|---|
update:modelValue | string | 查询文本变化时触发。 |
queryChange | string | 与 update:modelValue 同值,供不用 v-model 的宿主监听。 |
select | SearchPanelItem | 点击或按 Enter 选中结果时触发。 |
clear | - | 通过清除按钮或 Esc 清空时触发。 |
| 插槽名 | 作用域 | 说明 |
|---|
item | { item, active, query } | 替换单行内容。 |
empty | { query } | 替换空态。 |
footer | - | 列表下方、卡片内部的内容。 |
| 名称 | 说明 |
|---|
focus() | 聚焦输入框。 |
blur() | 让输入框失焦。 |
clear() | 清空查询并派发 clear。 |
| 名称 | 说明 |
|---|
SearchPanelItem | { id, label, keywords?, disabled? };keywords 参与内建匹配但不显示。 |
- 内联渲染:无遮罩、无模态语义、无焦点陷阱,可放进页面、侧栏或浮层。
- ↑ ↓ 两端循环并跳过禁用项,Home / End 跳到首尾可用项,Enter 选中,Esc 在有内容时清空;输入法组合期间忽略 Enter。
- 遵循 combobox 范式:输入框是带
aria-autocomplete="list"、aria-controls、aria-activedescendant 的 role="combobox";行是 tabindex="-1" 的 role="option",焦点始终留在输入框。 - 高亮由
is-active 表示,鼠标移动时同步到指针所在行。 - 选中结果不回写输入框,由宿主处理
select。 - 查询不足
emptyThreshold 个字符时,无匹配也不显示空态。
- 空态复用
TxSearchEmpty,只通过其公开 CSS 变量与 icon 插槽调整。 - 改编自 Beautiful UI,© 2026 Shane Levine,MIT 协议;键盘导航与 ARIA 为新增。
- 源码:
packages/tuffex/packages/components/src/search-panel/。
查看源码packages/tuffex/packages/components/src/search-panel/index.ts