name	frontend-patterns
description	React、Next.js、状态管理（State Management）、性能优化（Performance Optimization）及 UI 最佳实践的前端开发模式。
origin	ECC

前端开发模式 (Frontend Development Patterns)

适用于 React、Next.js 和高性能用户界面的现代前端模式。

何时激活 (When to Activate)

构建 React 组件（组合、Props、渲染）时
管理状态（useState、useReducer、Zustand、Context）时
实现数据获取（SWR、React Query、服务端组件）时
优化性能（记忆化、虚拟化、代码分割）时
处理表单（验证、受控输入、Zod 模式）时
处理客户端路由和导航时
构建具备可访问性（Accessible）且响应式的 UI 模式时

组件模式 (Component Patterns)

组合优于继承 (Composition Over Inheritance)

// ✅ 推荐：组件组合 (Component composition)
interface CardProps {
  children: React.ReactNode
  variant?: 'default' | 'outlined'
}

export function Card({ children, variant = 'default' }: CardProps) {
  return <div className={`card card-${variant}`}>{children}</div>
}

export function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="card-header">{children}</div>
}

export function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>
}

// 使用示例
<Card>
  <CardHeader>标题</CardHeader>
  <CardBody>内容</CardBody>
</Card>

复合组件 (Compound Components)

interface TabsContextValue {
  activeTab: string
  setActiveTab: (tab: string) => void
}

const TabsContext = createContext<TabsContextValue | undefined>(undefined)

export function Tabs({ children, defaultTab }: {
  children: React.ReactNode
  defaultTab: string
}) {
  const [activeTab, setActiveTab] = useState(defaultTab)

  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  )
}

export function TabList({ children }: { children: React.ReactNode }) {
  return <div className="tab-list">{children}</div>
}

export function Tab({ id, children }: { id: string, children: React.ReactNode }) {
  const context = useContext(TabsContext)
  if (!context) throw new Error('Tab 必须在 Tabs 内部使用')

  return (
    <button
      className={context.activeTab === id ? 'active' : ''}
      onClick={() => context.setActiveTab(id)}
    >
      {children}
    </button>
  )
}

// 使用示例
<Tabs defaultTab="overview">
  <TabList>
    <Tab id="overview">概览</Tab>
    <Tab id="details">详情</Tab>
  </TabList>
</Tabs>

渲染属性模式 (Render Props Pattern)

interface DataLoaderProps<T> {
  url: string
  children: (data: T | null, loading: boolean, error: Error | null) => React.ReactNode
}

export function DataLoader<T>({ url, children }: DataLoaderProps<T>) {
  const [data, setData] = useState<T | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    fetch(url)
      .then(res => res.json())
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false))
  }, [url])

  return <>{children(data, loading, error)}</>
}

// 使用示例
<DataLoader<Market[]> url="/api/markets">
  {(markets, loading, error) => {
    if (loading) return <Spinner />
    if (error) return <Error error={error} />
    return <MarketList markets={markets!} />
  }}
</DataLoader>

自定义钩子模式 (Custom Hooks Patterns)

状态管理钩子 (State Management Hook)

export function useToggle(initialValue = false): [boolean, () => void] {
  const [value, setValue] = useState(initialValue)

  const toggle = useCallback(() => {
    setValue(v => !v)
  }, [])

  return [value, toggle]
}

// 使用示例
const [isOpen, toggleOpen] = useToggle()

异步数据获取钩子 (Async Data Fetching Hook)

interface UseQueryOptions<T> {
  onSuccess?: (data: T) => void
  onError?: (error: Error) => void
  enabled?: boolean
}

export function useQuery<T>(
  key: string,
  fetcher: () => Promise<T>,
  options?: UseQueryOptions<T>
) {
  const [data, setData] = useState<T | null>(null)
  const [error, setError] = useState<Error | null>(null)
  const [loading, setLoading] = useState(false)

  const refetch = useCallback(async () => {
    setLoading(true)
    setError(null)

    try {
      const result = await fetcher()
      setData(result)
      options?.onSuccess?.(result)
    } catch (err) {
      const error = err as Error
      setError(error)
      options?.onError?.(error)
    } finally {
      setLoading(false)
    }
  }, [fetcher, options])

  useEffect(() => {
    if (options?.enabled !== false) {
      refetch()
    }
  }, [key, refetch, options?.enabled])

  return { data, error, loading, refetch }
}

// 使用示例
const { data: markets, loading, error, refetch } = useQuery(
  'markets',
  () => fetch('/api/markets').then(r => r.json()),
  {
    onSuccess: data => console.log('已获取', data.length, '个市场'),
    onError: err => console.error('失败：', err)
  }
)

防抖钩子 (Debounce Hook)

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value)
    }, delay)

    return () => clearTimeout(handler)
  }, [value, delay])

  return debouncedValue
}

// 使用示例
const [searchQuery, setSearchQuery] = useState('')
const debouncedQuery = useDebounce(searchQuery, 500)

useEffect(() => {
  if (debouncedQuery) {
    performSearch(debouncedQuery)
  }
}, [debouncedQuery])

状态管理模式 (State Management Patterns)

Context + Reducer 模式 (Context + Reducer Pattern)

interface State {
  markets: Market[]
  selectedMarket: Market | null
  loading: boolean
}

type Action =
  | { type: 'SET_MARKETS'; payload: Market[] }
  | { type: 'SELECT_MARKET'; payload: Market }
  | { type: 'SET_LOADING'; payload: boolean }

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'SET_MARKETS':
      return { ...state, markets: action.payload }
    case 'SELECT_MARKET':
      return { ...state, selectedMarket: action.payload }
    case 'SET_LOADING':
      return { ...state, loading: action.payload }
    default:
      return state
  }
}

const MarketContext = createContext<{
  state: State
  dispatch: Dispatch<Action>
} | undefined>(undefined)

export function MarketProvider({ children }: { children: React.ReactNode }) {
  const [state, dispatch] = useReducer(reducer, {
    markets: [],
    selectedMarket: null,
    loading: false
  })

  return (
    <MarketContext.Provider value={{ state, dispatch }}>
      {children}
    </MarketContext.Provider>
  )
}

export function useMarkets() {
  const context = useContext(MarketContext)
  if (!context) throw new Error('useMarkets 必须在 MarketProvider 内部使用')
  return context
}

性能优化 (Performance Optimization)

记忆化 (Memoization)

// ✅ 使用 useMemo 处理昂贵的计算
const sortedMarkets = useMemo(() => {
  return markets.sort((a, b) => b.volume - a.volume)
}, [markets])

// ✅ 使用 useCallback 处理传递给子组件的函数
const handleSearch = useCallback((query: string) => {
  setSearchQuery(query)
}, [])

// ✅ 使用 React.memo 处理纯组件
export const MarketCard = React.memo<MarketCardProps>(({ market }) => {
  return (
    <div className="market-card">
      <h3>{market.name}</h3>
      <p>{market.description}</p>
    </div>
  )
})

代码分割与懒加载 (Code Splitting & Lazy Loading)

import { lazy, Suspense } from 'react'

// ✅ 懒加载重型组件
const HeavyChart = lazy(() => import('./HeavyChart'))
const ThreeJsBackground = lazy(() => import('./ThreeJsBackground'))

export function Dashboard() {
  return (
    <div>
      <Suspense fallback={<ChartSkeleton />}>
        <HeavyChart data={data} />
      </Suspense>

      <Suspense fallback={null}>
        <ThreeJsBackground />
      </Suspense>
    </div>
  )
}

长列表虚拟化 (Virtualization for Long Lists)

import { useVirtualizer } from '@tanstack/react-virtual'

export function VirtualMarketList({ markets }: { markets: Market[] }) {
  const parentRef = useRef<HTMLDivElement>(null)

  const virtualizer = useVirtualizer({
    count: markets.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 100,  // 预估行高
    overscan: 5  // 额外渲染的条目数
  })

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div
        style={{
          height: `${virtualizer.getTotalSize()}px`,
          position: 'relative'
        }}
      >
        {virtualizer.getVirtualItems().map(virtualRow => (
          <div
            key={virtualRow.index}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`
            }}
          >
            <MarketCard market={markets[virtualRow.index]} />
          </div>
        ))}
      </div>
    </div>
  )
}

表单处理模式 (Form Handling Patterns)

带验证的受控表单 (Controlled Form with Validation)

interface FormData {
  name: string
  description: string
  endDate: string
}

interface FormErrors {
  name?: string
  description?: string
  endDate?: string
}

export function CreateMarketForm() {
  const [formData, setFormData] = useState<FormData>({
    name: '',
    description: '',
    endDate: ''
  })

  const [errors, setErrors] = useState<FormErrors>({})

  const validate = (): boolean => {
    const newErrors: FormErrors = {}

    if (!formData.name.trim()) {
      newErrors.name = '名称是必填项'
    } else if (formData.name.length > 200) {
      newErrors.name = '名称必须在 200 个字符以内'
    }

    if (!formData.description.trim()) {
      newErrors.description = '描述是必填项'
    }

    if (!formData.endDate) {
      newErrors.endDate = '截止日期是必填项'
    }

    setErrors(newErrors)
    return Object.keys(newErrors).length === 0
  }

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()

    if (!validate()) return

    try {
      await createMarket(formData)
      // 成功处理
    } catch (error) {
      // 错误处理
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={formData.name}
        onChange={e => setFormData(prev => ({ ...prev, name: e.target.value }))}
        placeholder="市场名称"
      />
      {errors.name && <span className="error">{errors.name}</span>}

      {/* 其他字段 */}

      <button type="submit">创建市场</button>
    </form>
  )
}

错误边界模式 (Error Boundary Pattern)

interface ErrorBoundaryState {
  hasError: boolean
  error: Error | null
}

export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  ErrorBoundaryState
> {
  state: ErrorBoundaryState = {
    hasError: false,
    error: null
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error }
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('错误边界捕获到错误：', error, errorInfo)
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <h2>出错了</h2>
          <p>{this.state.error?.message}</p>
          <button onClick={() => this.setState({ hasError: false })}>
            重试
          </button>
        </div>
      )
    }

    return this.props.children
  }
}

// 使用示例
<ErrorBoundary>
  <App />
</ErrorBoundary>

动画模式 (Animation Patterns)

Framer Motion 动画 (Framer Motion Animations)

import { motion, AnimatePresence } from 'framer-motion'

// ✅ 列表动画
export function AnimatedMarketList({ markets }: { markets: Market[] }) {
  return (
    <AnimatePresence>
      {markets.map(market => (
        <motion.div
          key={market.id}
          initial={{ opacity: 0, y: 20 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: -20 }}
          transition={{ duration: 0.3 }}
        >
          <MarketCard market={market} />
        </motion.div>
      ))}
    </AnimatePresence>
  )
}

// ✅ 模态框动画
export function Modal({ isOpen, onClose, children }: ModalProps) {
  return (
    <AnimatePresence>
      {isOpen && (
        <>
          <motion.div
            className="modal-overlay"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            onClick={onClose}
          />
          <motion.div
            className="modal-content"
            initial={{ opacity: 0, scale: 0.9, y: 20 }}
            animate={{ opacity: 1, scale: 1, y: 0 }}
            exit={{ opacity: 0, scale: 0.9, y: 20 }}
          >
            {children}
          </motion.div>
        </>
      )}
    </AnimatePresence>
  )
}

可访问性模式 (Accessibility Patterns)

键盘导航 (Keyboard Navigation)

export function Dropdown({ options, onSelect }: DropdownProps) {
  const [isOpen, setIsOpen] = useState(false)
  const [activeIndex, setActiveIndex] = useState(0)

  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault()
        setActiveIndex(i => Math.min(i + 1, options.length - 1))
        break
      case 'ArrowUp':
        e.preventDefault()
        setActiveIndex(i => Math.max(i - 1, 0))
        break
      case 'Enter':
        e.preventDefault()
        onSelect(options[activeIndex])
        setIsOpen(false)
        break
      case 'Escape':
        setIsOpen(false)
        break
    }
  }

  return (
    <div
      role="combobox"
      aria-expanded={isOpen}
      aria-haspopup="listbox"
      onKeyDown={handleKeyDown}
    >
      {/* 下拉菜单实现 */}
    </div>
  )
}

焦点管理 (Focus Management)

export function Modal({ isOpen, onClose, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null)
  const previousFocusRef = useRef<HTMLElement | null>(null)

  useEffect(() => {
    if (isOpen) {
      // 保存当前获得焦点的元素
      previousFocusRef.current = document.activeElement as HTMLElement

      // 聚焦到模态框
      modalRef.current?.focus()
    } else {
      // 关闭时恢复焦点
      previousFocusRef.current?.focus()
    }
  }, [isOpen])

  return isOpen ? (
    <div
      ref={modalRef}
      role="dialog"
      aria-modal="true"
      tabIndex={-1}
      onKeyDown={e => e.key === 'Escape' && onClose()}
    >
      {children}
    </div>
  ) : null
}

记住：现代前端模式使构建可维护、高性能的用户界面成为可能。请根据项目的复杂度选择合适的模式。

frontend-patterns

المزيد من هذا المستودع

前端开发模式 (Frontend Development Patterns)

何时激活 (When to Activate)

组件模式 (Component Patterns)

组合优于继承 (Composition Over Inheritance)

复合组件 (Compound Components)

渲染属性模式 (Render Props Pattern)

自定义钩子模式 (Custom Hooks Patterns)

状态管理钩子 (State Management Hook)

异步数据获取钩子 (Async Data Fetching Hook)

防抖钩子 (Debounce Hook)

状态管理模式 (State Management Patterns)

Context + Reducer 模式 (Context + Reducer Pattern)

性能优化 (Performance Optimization)

记忆化 (Memoization)

代码分割与懒加载 (Code Splitting & Lazy Loading)

长列表虚拟化 (Virtualization for Long Lists)

表单处理模式 (Form Handling Patterns)

带验证的受控表单 (Controlled Form with Validation)

错误边界模式 (Error Boundary Pattern)

动画模式 (Animation Patterns)

Framer Motion 动画 (Framer Motion Animations)

可访问性模式 (Accessibility Patterns)

键盘导航 (Keyboard Navigation)

焦点管理 (Focus Management)

前端开发模式 (Frontend Development Patterns)

何时激活 (When to Activate)

组件模式 (Component Patterns)

组合优于继承 (Composition Over Inheritance)

复合组件 (Compound Components)

渲染属性模式 (Render Props Pattern)

自定义钩子模式 (Custom Hooks Patterns)

状态管理钩子 (State Management Hook)

异步数据获取钩子 (Async Data Fetching Hook)

防抖钩子 (Debounce Hook)

状态管理模式 (State Management Patterns)

Context + Reducer 模式 (Context + Reducer Pattern)

性能优化 (Performance Optimization)

记忆化 (Memoization)

代码分割与懒加载 (Code Splitting & Lazy Loading)

长列表虚拟化 (Virtualization for Long Lists)

表单处理模式 (Form Handling Patterns)

带验证的受控表单 (Controlled Form with Validation)

错误边界模式 (Error Boundary Pattern)

动画模式 (Animation Patterns)

Framer Motion 动画 (Framer Motion Animations)

可访问性模式 (Accessibility Patterns)

键盘导航 (Keyboard Navigation)

焦点管理 (Focus Management)

المزيد من هذا المستودع