---
title: "SidebarNav 侧边导航"
description: "带搜索与分组的工作区侧边导航"
category: Navigation
status: beta
since: 0.3.9
tags: [navigation, sidebar, workspace, search]
syncStatus: reviewed
verified: true
---

## 用法

### 工作区导航
`search-hint="/"` 让 `/` 聚焦搜索框；浅色高亮块跟随指针移动。
:::TuffDemoWrapper{demo="SidebarNavSidebarNavDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSidebarNav
      v-model="active"
      v-model:query="query"
      :items="items"
      :groups="groups"
      :workspace="{ name: 'Creamery Ops', description: 'Production Workspace' }"
      search-placeholder="Quick search"
      search-hint="/"
      action-label="New task"
      @select="onSelect"
      @action="onNewTask"
    >
      <template #item-icon="{ item }">
        <svg viewBox="0 0 24 24"><path :d="icons[item.value]" /></svg>
      </template>
    </TxSidebarNav>
  </template>
---
:::

### 最佳实践

- 图标经 `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](https://www.beautifului.dev)，© 2026 Shane Levine，MIT 协议。

<TuffDocSourceLink />
