组件/SearchPanel 内联搜索面板

SearchPanel 内联搜索面板

输入框、实时结果与空态合为一体的内联搜索卡片

Verified自 0.3.9

用法

实时过滤

Loading demo...

最佳实践

  • 全局唤起的命令面板用 TxCommandPalette;版面内长驻的搜索区用本组件,两者键盘契约一致。
  • 用作命令列表时在 select 中执行动作并清空查询;用作筛选器时保留查询。
  • 远端搜索传 :filter="items => items" 关闭内建匹配,在 queryChange 中自行防抖取数。
  • 同义词放进 keywords;不可用的项设 disabled 置灰,不要从 items 中删除。
  • 按最常见的结果数设定 minHeight,过小会重新出现跳动。

API 参考

属性

属性名类型默认值说明
modelValuestring''查询文本,配合 v-model。
itemsSearchPanelItem[][]候选项。
placeholderstring'Search'输入框占位文本。
ariaLabelstring-输入框的无障碍名称;缺省时用 placeholder。
idleCountnumber5空查询时显示的条数;0 显示全部。
emptyThresholdnumber3显示空态所需的最短查询长度。
emptyTitlestring'No results found'空态标题。
emptyDescriptionstring'Adjust your search to try again'空态说明。
clearLabelstring'Clear search'清除按钮的无障碍名称。
listLabelstring'Search results'结果列表的无障碍名称。
minHeightnumber | string248预留高度,结果增减时版面不跳动。
filter(items, query) => items-替换内建匹配:对 label 与 keywords 不区分大小写的 includes。
clearablebooleantrue显示清除按钮。
disabledbooleanfalse禁用输入。

事件

事件名载荷说明
update:modelValuestring查询文本变化时触发。
queryChangestring与 update:modelValue 同值,供不用 v-model 的宿主监听。
selectSearchPanelItem点击或按 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