JSOS
开发指南

侧边栏设计规范

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>
  )
}

最佳实践

  1. 断点:移动端检测使用 640px(Tailwind sm),addEventListener('resize') 监听
  2. 样式:Desktop 侧边栏使用 bg-muted/30;Mobile 展开时用 bg-background(覆盖 backdrop)
  3. 关闭时机:backdrop 点击、选中导航项后自动关闭(仅 mobile)
  4. 选中态:bg-primary/10 text-primary font-medium,折叠/展开保持统一
  5. 动画:transition-all duration-200 确保折叠/展开平滑
  6. 图标大小:侧边栏图标用 size-4(16px)或 size-4.5(18px)
  7. tooltip:仅折叠态渲染 Tooltip,展开态不渲染

参考实现

  • 应用管理器主界面侧边栏(App.jsx)— nav 模式
  • 添加小组件页侧边栏(AddWidget.jsx)— app list 模式

On this page