开发指南
侧边栏设计规范
GUI 应用侧边栏的响应式设计模式 — 桌面端折叠/展开、移动端 Drawer、Tooltip 用法
侧边栏设计规范
所有 GUI 应用的侧边栏应遵循统一的设计模式,确保桌面端和移动端的一致性。
核心原则
- 桌面端(≥640px):侧边栏在布局流内(
shrink-0),折叠仅 56px 宽 - 移动端(<640px):折叠为固定窄条,展开为 Drawer 覆盖层 + backdrop
- 折叠态:仅显示图标,hover 时通过 coss-ui Tooltip 展示完整文本
侧边栏状态
| 状态 | 宽度 | 内容 | Toggle 图标 |
|---|---|---|---|
| 展开 | w-56(224px) | 完整文字 + Badge + 搜索 | PanelLeftClose |
| 折叠 | w-14(56px) | 仅图标 | PanelLeft |
响应式行为
Desktop(≥640px)
侧边栏为 shrink-0,在 flex 流内占据宽度:
[sidebar w-56/w-14] | [content flex-1]Mobile(<640px)
- 折叠:
fixed left-0 z-50 h-full w-14,始终固定左侧,内容区pl-14 - 展开:
fixed left-0 z-50 h-full w-56覆盖层,半透明 backdrop(bg-black/32 backdrop-blur-sm),点击 backdrop 关闭
← backdrop →
[sidebar-overlay] [content 全宽]使用 Tooltip
展开时文字直接显示,不必 tooltip。折叠时使用 coss-ui Tooltip 组件:
import { Tooltip, TooltipTrigger, TooltipPopup } from '@/components/ui/tooltip'
<Tooltip>
<TooltipTrigger
render={
<button onClick={...} className="..." />
}
>
<Icon />
{!collapsed && <span>Label</span>}
</TooltipTrigger>
{collapsed && (
<TooltipPopup side="right">Label</TooltipPopup>
)}
</Tooltip>- 永远不使用 HTML
title属性 TooltipPopup的side固定为"right"- 仅在折叠时渲染
TooltipPopup
实现骨架
import { useState, useEffect } from 'react'
import { PanelLeft, PanelLeftClose } from 'lucide-react'
import { cn } from '@/lib/utils'
import { Tooltip, TooltipTrigger, TooltipPopup } from '@/components/ui/tooltip'
function SidebarLayout() {
const [collapsed, setCollapsed] = useState(true)
const [isMobile, setIsMobile] = useState(false)
useEffect(() => {
const check = () => setIsMobile(window.innerWidth < 640)
check()
addEventListener('resize', check)
return () => removeEventListener('resize', check)
}, [])
return (
<div className={cn('flex h-full min-h-0', isMobile ? 'pl-14' : '')}>
{isMobile && !collapsed && (
<div
className="fixed inset-0 z-40 bg-black/32 backdrop-blur-sm"
onClick={() => setCollapsed(true)}
/>
)}
<aside className={cn(
'border-r border-border flex flex-col transition-all duration-200',
collapsed ? 'w-14' : 'w-56',
isMobile
? 'fixed left-0 top-0 z-50 h-full bg-background'
: 'shrink-0'
)}>
<div className={cn(
'border-b border-border flex items-center shrink-0',
collapsed ? 'justify-center p-2' : 'justify-between p-2 pl-4'
)}>
{!collapsed && <h1 className="font-semibold text-base truncate">Title</h1>}
<button onClick={() => setCollapsed(!collapsed)}>
{collapsed ? <PanelLeft className="size-4" /> : <PanelLeftClose className="size-4" />}
</button>
</div>
<nav className="flex-1 p-2 space-y-1">
{items.map(item => (
<Tooltip key={item.id}>
<TooltipTrigger
render={
<button onClick={item.onClick} className={cn(
'w-full flex items-center rounded-lg text-sm transition-colors cursor-pointer',
collapsed ? 'justify-center px-2 py-2' : 'gap-2.5 px-3 py-2',
item.active && 'bg-primary/10 text-primary font-medium'
)} />
}
>
{item.icon}
{!collapsed && (
<span className="flex-1 text-left">{item.label}</span>
)}
</TooltipTrigger>
{collapsed && (
<TooltipPopup side="right">{item.label}</TooltipPopup>
)}
</Tooltip>
))}
</nav>
</aside>
<main className="flex-1 min-w-0">
{/* page content */}
</main>
</div>
)
}最佳实践
- 断点:移动端检测使用
640px(Tailwindsm),addEventListener('resize')监听 - 样式:Desktop 侧边栏使用
bg-muted/30;Mobile 展开时用bg-background(覆盖 backdrop) - 关闭时机:backdrop 点击、选中导航项后自动关闭(仅 mobile)
- 选中态:
bg-primary/10 text-primary font-medium,折叠/展开保持统一 - 动画:
transition-all duration-200确保折叠/展开平滑 - 图标大小:侧边栏图标用
size-4(16px)或size-4.5(18px) - tooltip:仅折叠态渲染 Tooltip,展开态不渲染
参考实现
- 应用管理器主界面侧边栏(
App.jsx)— nav 模式 - 添加小组件页侧边栏(
AddWidget.jsx)— app list 模式