SidebarNav 侧边导航
带搜索与分组的工作区侧边导航
用法
工作区导航
search-hint="/" 让 / 聚焦搜索框;浅色高亮块跟随指针移动。
Loading demo...
最佳实践
- 图标经
item-icon插槽传内联 SVG,尺寸与描边由组件统一。 - 项数超过十几条时启用搜索,而不是继续加分组。
- 远端搜索传
filter="items => items",并在update:query时替换items;否则结果会被内建匹配再过滤一次。 searchHint写单个可输入字符(会真正绑定),或写完整字形(如⌘K)并自行调用focusSearch();不要写Ctrl这类半截提示。- 徽标只放需要跟进的计数;装饰性数字会削弱真正的待办。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | SidebarNavItem[] | - | 导航项。 |
groups | SidebarNavGroup[] | - | 分组定义;未匹配分组的项排在最前且不带标题。 |
modelValue | string | number | - | 当前选中项(v-model)。 |
query | string | - | 搜索文本(v-model:query)。 |
workspace | SidebarNavWorkspace | - | 工作区信息;不传则不渲染切换行。 |
workspaceLabel | string | 'Switch workspace' | 切换按钮的可访问名。 |
searchPlaceholder | string | - | 搜索框占位文本;不传则不渲染搜索行。 |
searchLabel | string | - | 搜索框的可访问名,回退到 placeholder。 |
searchHint | string | - | 搜索行末的快捷键角标,如 /;单字符时同时绑定该键。 |
actionLabel | string | - | 主操作文案;不传则不渲染按钮。 |
filter | (items, query) => items | - | 替换内建匹配;远端场景传 items => items。 |
ariaLabel | string | 'Workspace' | <nav> 地标的可访问名。 |
indicatorDuration | number | 220 | 高亮块速度(ms),整体缩放滑行弹簧;小于 100 按 100 播放。 |
事件
| 事件名 | 载荷 | 说明 |
|---|---|---|
update:modelValue | SidebarNavValue | 选中项变化时触发。 |
update:query | string | 搜索文本变化时触发。 |
select | SidebarNavItem | 激活导航项时触发;禁用项不派发。 |
action | - | 按下主操作按钮时触发。 |
itemAction | SidebarNavItem | 按下行尾快捷操作时触发。 |
workspaceClick | - | 按下工作区切换行时触发。 |
插槽
| 名称 | 说明 |
|---|---|
workspace | 替换整个工作区切换行。 |
item-icon | 替换导航项的前置图标,作用域 { item, active }。 |
footer | 追加在分组下方。 |
暴露方法
| 名称 | 说明 |
|---|---|
focusSearch() | 聚焦搜索框,供宿主绑定自定义快捷键。 |
refreshIndicator() | 在观察器覆盖不到的布局变化后重新测量高亮块,直接落位。 |
类型
| 名称 | 说明 |
|---|---|
SidebarNavItem | { value, label, group?, icon?, badge?, action?, disabled? };icon 是图标类名,item-icon 插槽优先;badge 变化时重放弹出动画。 |
SidebarNavGroup | { key, label };label 用正常大小写,由 CSS 转大写。 |
SidebarNavWorkspace | { name, description?, initials? };initials 缺省取 name 首字符。 |
概述
- 选中项带
aria-current="page";禁用项是真正的disabled按钮,不派发select。 - 高亮块是指针而非选中态:跟随悬停与键盘焦点,离开列表后回到选中项;选中态由字重与徽标表达。
- 只有目标变化时高亮块才滑行;首次测量与同一行的重新测量直接落位,减少动态效果时直接跳转且不淡入。
- 输入即过滤(对
label做大小写无关的includes),过滤后为空的分组连标题一起收起。 - 单字符
searchHint绑定document的 keydown,按下即聚焦搜索框;多字符(如⌘K)只渲染角标。焦点在输入区、按着 Meta / Ctrl / Alt、事件已被处理或没有搜索行时让路。 - 行尾快捷操作是行按钮的兄弟
<button>,触屏(hover: none)下常驻可见;分组标题经aria-labelledby关联各自的列表。
技术实现
- 高亮块由
useIndicatorBox测量、useJellyIndicator的滑行材质驱动;useIndicatorBox随组件导出(import { useIndicatorBox } from '@talex-touch/tuffex'),返回top / left / width / height,水平分段控件可复用。 - 快捷键监听挂在
document上;测试中启用enableAutoUnmount(afterEach),否则未卸载的实例会继续消费按键。 - 源码:
packages/tuffex/packages/components/src/sidebar-nav/。改编自 Beautiful UI,© 2026 Shane Levine,MIT 协议。
查看源码
packages/tuffex/packages/components/src/sidebar-nav/index.ts