组件/SidebarNav 侧边导航

SidebarNav 侧边导航

带搜索与分组的工作区侧边导航

Verified自 0.3.9

用法

工作区导航

search-hint="/" 让 / 聚焦搜索框;浅色高亮块跟随指针移动。

Loading demo...

最佳实践

  • 图标经 item-icon 插槽传内联 SVG,尺寸与描边由组件统一。
  • 项数超过十几条时启用搜索,而不是继续加分组。
  • 远端搜索传 filter="items => items",并在 update:query 时替换 items;否则结果会被内建匹配再过滤一次。
  • searchHint 写单个可输入字符(会真正绑定),或写完整字形(如 ⌘K)并自行调用 focusSearch();不要写 Ctrl 这类半截提示。
  • 徽标只放需要跟进的计数;装饰性数字会削弱真正的待办。

API 参考

属性

属性名类型默认值说明
itemsSidebarNavItem[]-导航项。
groupsSidebarNavGroup[]-分组定义;未匹配分组的项排在最前且不带标题。
modelValuestring | number-当前选中项(v-model)。
querystring-搜索文本(v-model:query)。
workspaceSidebarNavWorkspace-工作区信息;不传则不渲染切换行。
workspaceLabelstring'Switch workspace'切换按钮的可访问名。
searchPlaceholderstring-搜索框占位文本;不传则不渲染搜索行。
searchLabelstring-搜索框的可访问名,回退到 placeholder。
searchHintstring-搜索行末的快捷键角标,如 /;单字符时同时绑定该键。
actionLabelstring-主操作文案;不传则不渲染按钮。
filter(items, query) => items-替换内建匹配;远端场景传 items => items。
ariaLabelstring'Workspace'<nav> 地标的可访问名。
indicatorDurationnumber220高亮块速度(ms),整体缩放滑行弹簧;小于 100 按 100 播放。

事件

事件名载荷说明
update:modelValueSidebarNavValue选中项变化时触发。
update:querystring搜索文本变化时触发。
selectSidebarNavItem激活导航项时触发;禁用项不派发。
action-按下主操作按钮时触发。
itemActionSidebarNavItem按下行尾快捷操作时触发。
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