# UGSidebar 侧边栏

> 适配器：React；状态：available；slug：`sidebar`。

面向后台与多模块工作区的侧边导航，支持多级菜单、折叠浮层、可选上下文切换、搜索、品牌与页脚插槽、整数像素宽度、拖拽调整和移动端抽屉。

## 适用场景

- 后台、工具台和多模块工作区的主侧边导航。

## 不适用场景

- 临时补充内容使用 Drawer/Sheet；顶部站点导航使用 NavigationMenu。

## 公开入口

- 包入口：`@ug666/ui-react/components`
- 公开成员：`UGSidebar`
- 交互文档：[https://ui.ug666.top/react/components/sidebar](https://ui.ug666.top/react/components/sidebar)

```tsx
import { UGSidebar } from '@ug666/ui-react/components'
```

## 使用规则

- 父项只展开子菜单，叶子项才导航；模块首页应建成父项下的第一个叶子。
- 折叠叶子使用全局 Tooltip，多级菜单使用可操作浮层；active 只标记当前叶子，祖先分支会自动展开。
- 平台、租户、工作区或环境选择使用默认关闭的 contextSwitcher，不要伪装成一级菜单；与搜索同时使用时通过 contextSwitcherPlacement 明确顺序。
- 上下文选择、搜索、底部折叠、拖拽和 footer 默认关闭或为空，按项目需要显式开启；不要在业务 CSS 中穿透 Anatomy 重画侧栏。
- 展开宽度使用整数像素并受 min/max 约束；长菜单由 nav 自身滚动，响应式抽屉由 mobileOpen 合同控制。
- 活动菜单默认自动滚入侧栏可视区域；只有业务明确接管定位时才关闭 scrollActiveItemIntoView。
- 受控值使用当前组件声明的 value/onValueChange 或公开回调。
- 涉及 Hook、Portal 或浏览器状态时保留 client boundary。
- 只通过公开 Props、事件、插槽、class/className 和语义 Token 扩展。

## 相关候选

- [navigation-menu](https://ui.ug666.top/ai/react/components/navigation-menu.md)
- [drawer](https://ui.ug666.top/ai/react/components/drawer.md)

## 生成前检查

- 当前适配器是否真实提供该组件。
- 导入路径、组件名和 API 是否存在于当前版本类型声明。
- 是否覆盖长文本、窄容器、键盘、焦点、disabled、loading 和错误状态。