React 组件

UGSidebar 侧边栏

用于后台主导航和多模块工作台。组件统一管理品牌、可选上下文切换、菜单层级、活动态、折叠浮层、搜索、可选页脚、宽度和移动抽屉；业务只提供导航数据与开关配置。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx
import { UGSidebar, type UGSidebarItem } from '@ug666/ui-react'

可配置后台预览

下方开关直接控制同一个真实 UGSidebar。除品牌分隔线外，上下文选择、搜索、页脚、底部收缩和边界拖拽均保持组件默认关闭。

预览控制

当前展开宽度 264px；拖拽打开后可操作侧栏右边界。

项目管理 / 项目概览

项目概览

内容区域独立收缩，长菜单只在侧栏内部滚动。

进行中

12

本周交付

5

团队成员

18

最近项目

1组件文档重构今天
2后台导航打磨今天
3主题令牌升级今天

顶部上下文切换

平台、租户、工作区或环境不属于导航层级时，应放进独立的上下文选择区，而不是伪装成第一个一级菜单。

默认关闭

只传入内容不会显示，必须同时开启 contextSwitcherVisible。

业务中立

组件只负责区域、间距和折叠合同，选择器与切换行为由项目提供。

折叠安全

侧栏收缩后该区域退出交互与可访问树，不挤占紧凑导航宽度。

菜单数据与导航规则

侧栏不接管业务路由，但严格区分父项和叶子项，避免一级菜单既展开又跳转。

父项

存在 children 时整行只切换展开状态，传入 href 也不会导航。

叶子项

叶子通过 href 导航；active 只标记当前叶子，祖先分支自动展开。

模块首页

需要可点击的模块概览时，将它显式建成父项下的第一个叶子。

折叠态与多级浮层

使用上方“折叠侧栏”后即可验证：叶子悬停立即显示全局 Tooltip，父项悬停或聚焦显示包含子菜单的可操作浮层。

折叠后仍保留语义

图标按钮保留 aria-label；活动叶子的图标保持普通图标色，只由背景、文字和左侧标记表达选中。

键盘和焦点

父项可通过键盘聚焦，Escape 关闭折叠浮层；叶子仍是正常链接，不把导航伪装成按钮。

尺寸、滚动与响应式

宽度、滚动容器和移动抽屉都有明确边界，不依赖消费项目补丁。

展开宽度
默认 256px，可受控或非受控
折叠宽度
固定 72px，保留可聚焦菜单
宽度调整
整数像素；方向键 8px，Shift 16px
长菜单
nav 自身滚动，不撑高页面

启用 responsive 后，窄屏使用遮罩抽屉；Escape、遮罩、关闭按钮或叶子链接都会通过 onMobileOpenChange 请求关闭。

推荐接入

先使用默认关闭的可选区域，再按真实产品需要逐项打开；footer 不传即完全为空。

tsx
import { FolderKanban, Gauge, Home, Settings } from 'lucide-react'
import { UGSidebar, type UGSidebarItem } from '@ug666/ui-react'

const items: UGSidebarItem[] = [
  { id: 'home', label: '控制台', href: '/dashboard', icon: Home },
  {
    id: 'projects',
    label: '项目管理',
    icon: FolderKanban,
    badge: 6,
    children: [
      { id: 'overview', label: '项目概览', href: '/projects', icon: Gauge, active: true },
      { id: 'settings', label: '项目设置', href: '/projects/settings', icon: Settings },
    ],
  },
]

export function AppSidebar() {
  return (
    <UGSidebar
      items={items}
      variant="dark"
      defaultWidth={264}
      headerDivider
      header={<strong>UG Workspace</strong>}
    />
  )
}

属性

导航与外观

属性类型默认值说明
itemsSidebarItem[]必填导航项列表；父项由 children 标记，叶子项通过 href 跳转。
variant'primary' | 'dark''primary'侧边栏视觉风格，dark 适合深色后台导航。
colorsUGNavigationColorsundefined自定义导航五色；传入后统一覆盖背景、文字、选中、悬停及辅助控件颜色。
activeStyle'highlight' | 'indicator''highlight'当前菜单项使用强调色块或侧边标记。
density'comfortable' | 'compact''comfortable'调整菜单项密度，不影响页面内其他组件。
scrollActiveItemIntoViewbooleantrue活动菜单变化后自动滚入侧栏可视区域；长目录无需业务手动定位。
className / stylestring / CSSProperties—只用于侧栏外部布局；不要穿透内部 Anatomy 重画菜单。

折叠状态

属性类型默认值说明
collapsedbooleanundefined受控折叠状态。
defaultCollapsedbooleanfalse非受控折叠初始状态。
onCollapsedChange(collapsed: boolean) => void—折叠状态变化回调。
collapsiblebooleanfalse在品牌区显示内置展开/折叠按钮。
bottomCollapsiblebooleanfalse在侧栏底部显示展开/折叠按钮。

展开宽度

属性类型默认值说明
resizablebooleanfalse允许桌面端拖动右边界调整宽度，并支持方向键、Home、End 与双击复位。
width / defaultWidthnumberundefined / 256受控或非受控展开宽度；无论是否开启拖拽都生效，并按整数像素应用。
minWidth / maxWidthnumber208 / 480展开宽度边界；最小值不会低于 160px。
onWidthChange(width: number) => void—拖动或键盘调整宽度后的回调。

搜索

属性类型默认值说明
searchablebooleanfalse显示内置菜单搜索；折叠时自动清空筛选并隐藏。
searchPlaceholderstring'搜索菜单...'菜单搜索占位文案。
searchDividersbooleantrue是否显示搜索区域上下分隔线。

品牌与扩展区域

属性类型默认值说明
headerReactNode—顶部品牌内容。
headerAlign'start' | 'center''start'顶部品牌内容的水平对齐方式。
headerDividerbooleantrue是否显示品牌区域下分隔线。
collapsedHeaderReactNode—使用外部折叠控制时，折叠态显示的紧凑品牌内容。
contextSwitcherReactNode—品牌区下方的业务中立插槽，适合工作区、租户、环境或文档平台选择。
contextSwitcherVisiblebooleanfalse显式开启顶部上下文切换区域；折叠时自动隐藏。
contextSwitcherDividersbooleanfalse是否显示上下文切换区域上下分隔线。
contextSwitcherPlacement'before-search' | 'after-search''after-search'控制上下文切换区域位于搜索区之前或之后；两个区域同时显示时共享紧凑间距。
footerReactNode—完全自定义底部区域；不传即不渲染。

移动端抽屉

属性类型默认值说明
responsivebooleanfalse启用移动端抽屉模式，并支持 Escape 关闭。
mobileOpenbooleanfalse移动端抽屉打开状态。
onMobileOpenChange(open: boolean) => void—Escape、遮罩、关闭按钮或叶子导航关闭抽屉时触发。

SidebarItem

属性类型默认值说明
idstring—稳定菜单标识；动态菜单建议提供。
label / iconstring / LucideIcon必填菜单文字与图标。
hrefstring'#'叶子菜单地址；含 children 的父项只负责展开，即使传入 href 也不跳转。
activebooleanfalse当前叶子状态；祖先分支会自动展开，但图标不会跟随高亮。
badgestring | number—菜单右侧短数量或短状态。
childrenSidebarItem[]—子菜单；模块首页请显式建成第一个叶子项。