响应式开发指南

概述

本指南说明如何在 Wegent 中开发响应式功能，遵循移动优先、组件分离的架构。

何时分离组件

✅ 使用独立的移动端/桌面端组件的情况：

布局结构存在根本性差异（>30% 差异）
- 示例：桌面端有永久侧边栏，移动端使用抽屉式
- 示例：桌面端显示多列布局，移动端显示单列
不同的交互模式
- 示例：桌面端使用下拉菜单，移动端使用底部弹出层
- 示例：桌面端有内联控件，移动端将它们整合到设置菜单中
需要性能优化
- 示例：移动端版本需要简化渲染以获得更好的性能
- 示例：代码分割有助于减小包体积

❌ 使用 Tailwind 响应式类的情况：

仅样式差异（间距、字体大小、颜色）

// 好：简单的样式调整
<div className="px-4 md:px-6 lg:px-8">
  <h1 className="text-lg md:text-xl lg:text-2xl">标题</h1>
</div>

简单的显示/隐藏场景

// 好：简单的可见性切换
<div className="hidden md:block">仅桌面端内容</div>
<div className="md:hidden">仅移动端内容</div>

轻微的布局调整

// 好：响应式 flex 方向
<div className="flex flex-col md:flex-row gap-4">
  {children}
</div>

架构模式

页面级分离

对于响应式差异显著的页面，使用以下模式：

app/(tasks)/chat/
├── page.tsx                 # 路由组件
├── ChatPageDesktop.tsx      # 桌面端实现
└── ChatPageMobile.tsx       # 移动端实现

路由组件 (page.tsx)：

'use client'

import dynamic from 'next/dynamic'
import { useIsMobile } from '@/features/layout/hooks/useMediaQuery'

// 使用代码分割的动态导入
const ChatPageDesktop = dynamic(
  () => import('./ChatPageDesktop').then(mod => ({ default: mod.ChatPageDesktop })),
  { ssr: false }
)

const ChatPageMobile = dynamic(
  () => import('./ChatPageMobile').then(mod => ({ default: mod.ChatPageMobile })),
  { ssr: false }
)

export default function ChatPage() {
  const isMobile = useIsMobile()

  return (
    <>
      {/* 共享的处理器和设置 */}
      <OidcTokenHandler />
      <OnboardingTour {...props} />

      {/* 路由到适当的组件 */}
      {isMobile ? <ChatPageMobile /> : <ChatPageDesktop />}
    </>
  )
}

组件级分离

对于具有不同移动端/桌面端实现的单个组件：

features/tasks/components/input/
├── ChatInputControls.tsx        # 桌面端版本（默认）
└── MobileChatInputControls.tsx  # 移动端版本

模式：

// ChatInputControls.tsx（包含路由逻辑）
export function ChatInputControls(props: Props) {
  const isMobile = useIsMobile()

  if (isMobile) {
    return <MobileChatInputControls {...props} />
  }

  // 桌面端实现
  return (
    <div className="flex items-center gap-3">
      {/* 桌面端布局 */}
    </div>
  )
}

响应式断点

Wegent 使用以下断点系统：

断点	屏幕尺寸	用途
Mobile	≤767px	触摸优化 UI，带抽屉式侧边栏
Tablet	768px-1023px	使用桌面端布局，带轻微调整
Desktop	≥1024px	全功能 UI，所有控件

Hook 用法：

import { useIsMobile, useIsTablet, useIsDesktop } from '@/features/layout/hooks/useMediaQuery'

function MyComponent() {
  const isMobile = useIsMobile()    // max-width: 767px
  const isTablet = useIsTablet()    // 768px - 1023px
  const isDesktop = useIsDesktop()  // min-width: 1024px

  // 注意：平板设备使用桌面端布局
  return isMobile ? <MobileView /> : <DesktopView />
}

移动优先最佳实践

1. 触摸友好的目标

移动端上的所有交互元素必须满足最小触摸目标尺寸：

// 触摸目标常量
const MOBILE_TOUCH_TARGET = {
  minHeight: '44px',  // iOS 人机界面指南
  minWidth: '44px',
  padding: '12px',
}

// 使用示例
<Button className="h-11 min-w-[44px] px-4">
  <Icon className="h-5 w-5" />
</Button>

✅ 好的示例：

// 触摸友好的按钮
<button className="h-11 min-w-[44px] p-3 rounded-lg">
  <MenuIcon className="h-5 w-5" />
</button>

// 触摸友好的列表项
<div className="p-4 min-h-[44px] cursor-pointer hover:bg-surface">
  列表项
</div>

❌ 不好的示例：

// 触摸目标太小
<button className="h-6 w-6 p-1">
  <MenuIcon />
</button>

// 内边距不足
<div className="p-1 cursor-pointer">
  可点击项
</div>

2. 移动端导航模式

抽屉式侧边栏：

import { Transition, Dialog } from '@headlessui/react'

function MobileSidebar({ isOpen, onClose }: Props) {
  return (
    <Transition show={isOpen} as={Dialog} onClose={onClose}>
      {/* 遮罩层 */}
      <Transition.Child
        enter="transition-opacity ease-out duration-300"
        enterFrom="opacity-0"
        enterTo="opacity-100"
        leave="transition-opacity ease-in duration-200"
        leaveFrom="opacity-100"
        leaveTo="opacity-0"
        className="fixed inset-0 bg-black/30 z-40"
      />

      {/* 抽屉 */}
      <Transition.Child
        enter="transition ease-out duration-300 transform"
        enterFrom="-translate-x-full"
        enterTo="translate-x-0"
        leave="transition ease-in duration-200 transform"
        leaveFrom="translate-x-0"
        leaveTo="-translate-x-full"
        className="fixed left-0 top-0 bottom-0 w-80 max-w-[85vw] bg-base border-r z-50"
      >
        {/* 侧边栏内容 */}
      </Transition.Child>
    </Transition>
  )
}

3. 性能优化

代码分割：

// 使用动态导入进行基于路由的代码分割
const MobileComponent = dynamic(() => import('./MobileComponent'), {
  ssr: false,
  loading: () => <PageSkeleton />,
})

懒加载：

import { lazy, Suspense } from 'react'

const HeavyComponent = lazy(() => import('./HeavyComponent'))

function MyComponent() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <HeavyComponent />
    </Suspense>
  )
}

图片优化：

import Image from 'next/image'

<Image
  src={avatarUrl}
  width={40}
  height={40}
  loading="lazy"
  alt="用户头像"
/>

4. 处理水合不匹配

使用 useIsMobile() hook 时，避免水合不匹配：

// ✅ 好：抑制响应式组件的水合警告
<div suppressHydrationWarning>
  {isMobile ? <MobileView /> : <DesktopView />}
</div>

// ✅ 更好：使用动态导入避免在服务器上渲染
const MobileView = dynamic(() => import('./MobileView'), { ssr: false })
const DesktopView = dynamic(() => import('./DesktopView'), { ssr: false })

代码示例

示例 1：完整的组件分离

场景： 输入控件在移动端和桌面端有根本不同的布局。

// ChatInputControls.tsx（桌面端版本）
export function ChatInputControls(props: Props) {
  const isMobile = useIsMobile()

  if (isMobile) {
    return <MobileChatInputControls {...props} />
  }

  // 桌面端：所有控件内联
  return (
    <div className="flex items-center justify-between px-3 gap-3">
      <div className="flex-1 flex items-center gap-3">
        <ChatContextInput {...contextProps} />
        <AttachmentButton {...attachmentProps} />
        <ClarificationToggle {...clarificationProps} />
        <ModelSelector {...modelProps} />
        <RepositorySelector {...repoProps} />
      </div>
      <div className="flex items-center gap-2">
        <QuotaUsage />
        <SendButton {...sendProps} />
      </div>
    </div>
  )
}

// MobileChatInputControls.tsx（移动端版本）
export function MobileChatInputControls(props: Props) {
  const [menuOpen, setMenuOpen] = useState(false)

  // 移动端：简化，设置放在下拉菜单中
  return (
    <div className="flex items-center justify-between px-3 gap-2 pb-2 pt-1">
      <div className="flex items-center gap-1">
        <AttachmentButton {...attachmentProps} />
        <ChatContextInput {...contextProps} />

        {/* 设置下拉菜单整合不常用的控件 */}
        <DropdownMenu open={menuOpen} onOpenChange={setMenuOpen}>
          <DropdownMenuTrigger asChild>
            <Button variant="ghost" size="sm" className="h-11 min-w-[44px]">
              <Settings2 className="h-5 w-5" />
            </Button>
          </DropdownMenuTrigger>
          <DropdownMenuContent>
            <ClarificationToggle {...clarificationProps} />
            <RepositorySelector {...repoProps} />
          </DropdownMenuContent>
        </DropdownMenu>
      </div>

      <div className="flex items-center gap-2">
        <MobileModelSelector {...modelProps} />
        <SendButton {...sendProps} compact />
      </div>
    </div>
  )
}

示例 2：共享逻辑，不同 UI

将共享逻辑提取到自定义 hook：

// hooks/useChatInputLogic.ts
export function useChatInputLogic(props: Props) {
  const [selectedModel, setSelectedModel] = useState(null)
  const [isStreaming, setIsStreaming] = useState(false)

  const handleSend = useCallback(() => {
    // 共享发送逻辑
  }, [])

  const handleStop = useCallback(() => {
    // 共享停止逻辑
  }, [])

  return {
    selectedModel,
    setSelectedModel,
    isStreaming,
    handleSend,
    handleStop,
  }
}

// 在移动端和桌面端组件中使用
function ChatInputControls(props: Props) {
  const logic = useChatInputLogic(props)
  const isMobile = useIsMobile()

  return isMobile ? (
    <MobileChatInputControls {...logic} />
  ) : (
    <DesktopChatInputControls {...logic} />
  )
}

测试响应式组件

单元测试

import { render, screen } from '@testing-library/react'
import { useIsMobile } from '@/features/layout/hooks/useMediaQuery'

jest.mock('@/features/layout/hooks/useMediaQuery')

describe('ChatPage 响应式行为', () => {
  it('在小屏幕上渲染移动端版本', () => {
    ;(useIsMobile as jest.Mock).mockReturnValue(true)

    render(<ChatPage />)
    expect(screen.getByTestId('chat-page-mobile')).toBeInTheDocument()
  })

  it('在大屏幕上渲染桌面端版本', () => {
    ;(useIsMobile as jest.Mock).mockReturnValue(false)

    render(<ChatPage />)
    expect(screen.getByTestId('chat-page-desktop')).toBeInTheDocument()
  })

  it('移动端上触摸目标满足最小尺寸要求', () => {
    ;(useIsMobile as jest.Mock).mockReturnValue(true)

    render(<MobileChatInputControls {...props} />)
    const buttons = screen.getAllByRole('button')

    buttons.forEach(button => {
      const { height, width } = button.getBoundingClientRect()
      expect(height).toBeGreaterThanOrEqual(44)
      expect(width).toBeGreaterThanOrEqual(44)
    })
  })
})

E2E 测试 (Playwright)

// tests/e2e/responsive/mobile-navigation.spec.ts
import { test, expect } from '@playwright/test'

test.describe('移动端导航', () => {
  test.use({ viewport: { width: 375, height: 667 } }) // iPhone SE

  test('点击汉堡菜单应打开侧边栏', async ({ page }) => {
    await page.goto('/chat')
    await page.click('[aria-label="打开侧边栏"]')
    await expect(page.locator('[data-testid="mobile-sidebar"]')).toBeVisible()
  })

  test('点击遮罩层应关闭侧边栏', async ({ page }) => {
    await page.goto('/chat')
    await page.click('[aria-label="打开侧边栏"]')
    await page.click('.overlay') // 点击遮罩层
    await expect(page.locator('[data-testid="mobile-sidebar"]')).not.toBeVisible()
  })
})

test.describe('桌面端导航', () => {
  test.use({ viewport: { width: 1280, height: 720 } })

  test('应显示永久侧边栏', async ({ page }) => {
    await page.goto('/chat')
    await expect(page.locator('[data-testid="desktop-sidebar"]')).toBeVisible()
  })

  test('应支持侧边栏折叠', async ({ page }) => {
    await page.goto('/chat')
    await page.click('[aria-label="折叠侧边栏"]')
    await expect(page.locator('[data-testid="collapsed-sidebar"]')).toBeVisible()
  })
})

常见陷阱和解决方案

陷阱 1：水合不匹配

问题：

// ❌ 服务器渲染一种情况，客户端渲染另一种情况
function MyComponent() {
  const isMobile = useIsMobile()
  return isMobile ? <Mobile /> : <Desktop />
}

解决方案：

// ✅ 使用动态导入跳过 SSR
const Mobile = dynamic(() => import('./Mobile'), { ssr: false })
const Desktop = dynamic(() => import('./Desktop'), { ssr: false })

function MyComponent() {
  const isMobile = useIsMobile()
  return isMobile ? <Mobile /> : <Desktop />
}

陷阱 2：忘记触摸目标

问题：

// ❌ 按钮对触摸来说太小
<button className="h-6 w-6 p-1">
  <Icon />
</button>

解决方案：

// ✅ 触摸友好的尺寸
<button className="h-11 min-w-[44px] p-3">
  <Icon className="h-5 w-5" />
</button>

陷阱 3：重复业务逻辑

问题：

// ❌ 逻辑在移动端和桌面端组件中重复
function MobileComponent() {
  const [data, setData] = useState([])
  useEffect(() => { /* 获取逻辑 */ }, [])
  // ...
}

function DesktopComponent() {
  const [data, setData] = useState([])
  useEffect(() => { /* 相同的获取逻辑 */ }, [])
  // ...
}

解决方案：

// ✅ 将共享逻辑提取到自定义 hook
function useDataFetching() {
  const [data, setData] = useState([])
  useEffect(() => { /* 获取逻辑 */ }, [])
  return { data, setData }
}

function MobileComponent() {
  const { data, setData } = useDataFetching()
  // 仅移动端 UI
}

function DesktopComponent() {
  const { data, setData } = useDataFetching()
  // 仅桌面端 UI
}

性能优化检查清单

对移动端/桌面端页面组件使用 dynamic() 导入
为使用 useIsMobile() 的动态导入添加 { ssr: false }
实现加载骨架屏以提高感知性能
对所有图片使用 next/image 并设置 loading="lazy"
通过路由级代码分割最小化包体积
对长列表使用虚拟滚动（例如 @tanstack/react-virtual）
通过适当的事件处理优化触摸交互
在真实移动设备上测试，而不仅仅是浏览器 DevTools

无障碍访问考虑

// 始终包含适当的 ARIA 标签
<button
  aria-label="打开导航菜单"
  className="h-11 min-w-[44px]"
>
  <MenuIcon className="h-5 w-5" />
  <span className="sr-only">打开导航菜单</span>
</button>

// 支持键盘导航
<div
  role="button"
  tabIndex={0}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
  onClick={handleClick}
>
  交互元素
</div>

总结

分离组件 当布局差异超过 30%
使用 Tailwind 类 进行简单的样式调整
提取共享逻辑 到自定义 hooks
确保触摸目标 在移动端至少为 44px × 44px
使用动态导入 进行代码分割和性能优化
在真实设备上测试 以确保最佳用户体验
记录你的决策 以便未来维护

更多示例请参考：

/app/(tasks)/chat/ChatPageDesktop.tsx 和 ChatPageMobile.tsx
/app/(tasks)/code/CodePageDesktop.tsx 和 CodePageMobile.tsx
/features/tasks/components/input/ChatInputControls.tsx 和 MobileChatInputControls.tsx

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

响应式开发指南

概述

何时分离组件

✅ 使用独立的移动端/桌面端组件的情况：

❌ 使用 Tailwind 响应式类的情况：

架构模式

页面级分离

组件级分离

响应式断点

移动优先最佳实践

1. 触摸友好的目标

2. 移动端导航模式

3. 性能优化

4. 处理水合不匹配

代码示例

示例 1：完整的组件分离

示例 2：共享逻辑，不同 UI

测试响应式组件

单元测试

E2E 测试 (Playwright)

常见陷阱和解决方案

陷阱 1：水合不匹配

陷阱 2：忘记触摸目标

陷阱 3：重复业务逻辑

性能优化检查清单

无障碍访问考虑

总结

FilesExpand file tree

responsive-development.md

Latest commit

History

responsive-development.md

File metadata and controls

响应式开发指南

概述

何时分离组件

✅ 使用独立的移动端/桌面端组件的情况：

❌ 使用 Tailwind 响应式类的情况：

架构模式

页面级分离

组件级分离

响应式断点

移动优先最佳实践

1. 触摸友好的目标

2. 移动端导航模式

3. 性能优化

4. 处理水合不匹配

代码示例

示例 1：完整的组件分离

示例 2：共享逻辑，不同 UI

测试响应式组件

单元测试

E2E 测试 (Playwright)

常见陷阱和解决方案

陷阱 1：水合不匹配

陷阱 2：忘记触摸目标

陷阱 3：重复业务逻辑

性能优化检查清单

无障碍访问考虑

总结