# 反应最佳实践构建现代 React 和 Next.js 应用程序的综合指南。涵盖性能优化、组件架构、shadcn/ui 模式、运动动画、可访问性和 React 19+ 功能。 ## 何时申请在以下情况下请参考这些指南： * 编写新的 React 组件或 Next.js 页面 * 实现数据获取（客户端或服务器端） * 使用 shadcn/ui 组件构建 UI * 添加动画和微交互 * 审查代码的质量和性能 * 重构现有的 React/Next.js 代码 * 优化包大小或加载时间 ## 按优先级规则类别优先|类别 |影响 |前缀 ---|---|---|--- 1 |组件架构|关键 | `拱门-` 2 |消除瀑布|关键 | `异步-` 3 |捆绑包大小优化 |关键 | `捆绑-` 4 |服务器组件和操作 |高| `服务器-` 5 | shadcn/ui 模式 |高| `shadcn-` 6 |国家管理|中高| `状态-` 7 |运动与动画 |中 | `运动-` 8 |重新渲染优化 |中 | `重新渲染-` 9 |无障碍 |中 | `a11y-` 10 | 10 TypeScript 模式 |中 | `ts-` ** ** ## 1\.组件架构（关键） ### 快速参考 * `arch-function-components` \- 专门使用带钩子的功能组件 * `arch-composition-over-inheritance` \- 基于现有组件构建，不扩展 * `arch-single-responsibility` \- 每个组件应该做好一件事 * `arch-presentational-container` \- 在有益的情况下将 UI 与逻辑分开 * `arch-colocation` \- 将相关文件放在一起（组件、样式、测试） * `arch-avoid-prop-drilling` \- 使用上下文或组合作为深层道具 ### 关键原则 **仅功能组件** // 正确：带钩子的功能组件函数 UserProfile({ userId }: { userId: string }) { const { 数据：用户 } = useUser(userId) 返回

{用户?.name}

} // 错误：类组件类 UserProfile 扩展 React.Component { /* ... */ } **构图模式** // 正确：组合更小的组件函数 Card({ 孩子 }: { 孩子: React.ReactNode }) { 返回

{children}

} 函数 CardHeader({ 孩子 }: { 孩子: React.ReactNode }) { 返回

{children}

} // 用法 <卡片> 标题

内容

**避免支柱钻井** // 错误：通过多个级别传递 props <应用程序用户={用户}> <布局用户={用户}> <侧边栏用户={用户}> // 正确：使用 Context 来共享状态 const UserContext = createContext<用户 |空>(空) 函数应用程序（）{ 常量用户 = useCurrentUser() 返回（ <布局> <侧边栏> <用户菜单/> ） } ** ** ## 2\.消除瀑布（关键） ### 快速参考 * `async-defer-await` \- 将await移动到实际使用的分支中 * `异步并行` \- 使用 Promise.all() 进行独立操作 * `async-dependencies` \- 正确处理部分依赖关系 * `async-api-routes` \- 在 API 路由中尽早开始承诺，延迟等待 * `async-suspense-boundaries` \- 使用 Suspense 传输内容 ### 关键原则瀑布是第一大性能杀手。每个顺序等待都会增加完整的网络延迟。 **并行数据获取** // 错误：顺序瀑布异步函数 Page() { const 用户 = 等待 fetchUser() const posts = 等待 fetchPosts() 常量评论 = 等待 fetchComments() return

{/* 渲染 */}

} // 正确：并行获取异步函数 Page() { const [用户、帖子、评论] = wait Promise.all([ 获取用户(), 获取帖子(), 获取评论() ]） return

{/* 渲染 */}

} **战略悬念边界** // 当内容可用时流式传输函数页面（）{ 返回（

<标题/> <悬念后备={}> <帖子/> }> <评论/>

） } ** ** ## 3\.捆绑包大小优化（关键） ### 快速参考 * `bundle-barrel-imports` \- 直接导入，避免桶文件 * `bundle-dynamic-imports` \- 对重型组件使用 next/dynamic * `bundle-defer-third-party` \- 水合后加载分析/日志记录 * `bundle-conditional` \- 仅在激活功能时加载模块 * `bundle-preload` \- 在悬停/焦点时预加载以获得感知速度 ### 关键原则 **避免桶文件导入** // 错误：导入整个库从 '@/components' 导入 { Button } 从 '@/utils' 导入 { formatDate } // 正确：直接导入启用 tree-shaking 从 '@/components/ui/button' 导入 { Button } 从 '@/utils/date' 导入 { formatDate } **动态导入** 从“下一个/动态”导入动态 // 仅在需要时加载 const HeavyChart = 动态(() => import('./HeavyChart'), { 加载：() => , ssr: 假 }) 功能仪表板（{显示图表}）{ 返回显示图表？：空 } ** ** ## 4\.服务器组件和操作（高） ### 快速参考 * `server-default-server` \- 组件默认是服务器组件 * `server-use-client-boundary` \- 仅在需要时添加“使用客户端” * `server-actions` \- 使用服务器操作进行突变 * `server-cache-react` \- 使用 React.cache() 进行每个请求的重复数据删除 * `服务器序列化` \- 最小化传递给客户端组件的数据 ### 关键原则 **默认服务器组件** // 服务器组件（默认）- 可以是异步的异步函数 ProductPage({ id }: { id: string }) { const 产品 =等待 db.product.findUnique({ 其中：{ id } }) 返回 } // 客户端组件 - 仅当需要交互时 “使用客户端” 函数 AddToCartButton({ 产品 ID }: { 产品 ID: 字符串 }) { const [isPending, startTransition] = useTransition() 返回（ <按钮 onClick={() => startTransition(() => addToCart(productId))} 已禁用={正在等待} > 添加到购物车） } **服务器操作** // 动作.ts '使用服务器' 导出异步函数 createPost(formData: FormData) { const title = formData.get('title') 作为字符串 const content = formData.get('content') as string 等待 db.post.create({ 数据: { 标题, 内容 } }) revalidatePath('/帖子') } // 组件使用函数 CreatePostForm() { 返回（ <表单操作={createPost}> <输入名称=“标题”占位符=“标题”/>

<Button type="submit">创建帖子</Button>
        </形式>
      ）
    }

** **

## 5\. shadcn/ui 模式（高）

### 快速参考

* `shadcn-composition` \- 基于现有的 shadcn/ui 原语构建
  * `shadcn-variants` \- 对组件变体使用类方差权威
  * `shadcn-theme-integration` \- 使用 CSS 自定义属性进行主题化
  * `shadcn-accessibility` \- 利用 Radix 的内置可访问性
  * `shadcn-customization` \- 修改复制的组件，不要过度换行

### 核心原则

shadcn/ui 是围绕以下内容构建的：

* **开放代码**：组件被复制到您的项目中，完全可定制
  * **组合** ：每个组件都使用一个通用的、可组合的接口
  * **美丽的默认设置**：精心选择的默认样式
  * **默认辅助功能**：基于 Radix UI 原语构建

### 组件安装
    
    
    # 根据需要添加组件
    npx shadcn@最新添加按钮
    npx shadcn@最新添加卡
    npx shadcn@最新添加对话框
    npx shadcn@最新添加表单

### 构建自定义组件

**创作重于创作**
    
    
    // 正确：基于现有原语构建
    从 '@/components/ui/card' 导入 { Card, CardHeader, CardTitle, CardContent }
    从 '@/components/ui/badge' 导入 { Badge }
    
    接口 ProductCardProps {
      产品： 产品
      onSelect?: () => void
    }
    
    函数 ProductCard({ 产品, onSelect }: ProductCardProps) {
      返回（
        <卡片
          className =“光标指针悬停：shadow-md过渡阴影”
          onClick={onSelect}
        >
          <卡片标题>
            <div className="flex items-center justify- Between">
              <CardTitle>{产品.名称}</CardTitle>
              {product.isNew && <徽章>新</徽章>}
            </div>
          </卡头>
          <卡片内容>
            <p className="text-muted-foreground">{产品.描述}</p>
            <p className="text-lg font-bold mt-2">${product.price}</p>
          </卡片内容>
        </卡>
      ）
    }

**使用带有 CVA 的变体**
    
    
    从 'class-variance-authority' 导入 { cva, type VariantProps }
    从 '@/lib/utils' 导入 { cn }
    
    const statusBadgeVariants = cva(
      'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold',
      {
        变体：{
          状态：{
            待处理：'bg-yellow-100 text-yellow-800'，
            活动：'bg-green-100 text-green-800'，
            非活动：'bg-gray-100 text-gray-800'，
            错误：'bg-red-100 文本-red-800'，
          },
        },
        默认变体：{
          状态：'待定'，
        },
      }
    ）
    
    接口 StatusBadgeProps
      扩展 React.HTMLAttributes<HTMLSpanElement>,
        VariantProps<statusBadgeVariants 类型> {
      标签：字符串
    }
    
    函数 StatusBadge({ 状态, 标签, 类名, ...props }: StatusBadgeProps) {
      返回（
        <span className={cn(statusBadgeVariants({ status }), className)} {...props}>
          {标签}
        </span>
      ）
    }

### 常用 shadcn/ui 组件

**使用 React Hook Form + Zod 形成表单**
    
    
    “使用客户端”
    
    从 '@hookform/resolvers/zod' 导入 { zodResolver }
    从 'react-hook-form' 导入 { useForm }
    从 'zod' 导入 * as z
    从 '@/components/ui/button' 导入 { Button }
    导入{
      形式，
      表单控件，
      表格描述，
      表单字段，
      表单项，
      表单标签，
      表单消息，
    来自 '@/components/ui/form'
    从'@/components/ui/input'导入{输入}
    
    const formSchema = z.object({
      email: z.string().email('无效的电子邮件地址'),
      密码: z.string().min(8, '密码必须至少8个字符'),
    })
    
    函数登录表单（）{
      const form = useForm<z.infer<typeof formSchema>>({
        解析器：zodResolver(formSchema),
        默认值：{
          电子邮件：''，
          密码: '',
        },
      })
    
      函数 onSubmit(值: z.infer<typeof formSchema>) {
        控制台.log(值)
      }
    
      返回（
        <表格{...表格}>
          <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
            <表单域
              控制={form.control}
              姓名=“电子邮件”
              渲染={({字段})=>(
                <表单项>
                  <FormLabel>电子邮件</FormLabel>
                  <表单控件>
                    <输入占位符=“you@example.com”{...字段} />
                  </表单控件>
                  <表单消息/>
                </表单项>
              )}
            />
            <表单域
              控制={form.control}
              名称=“密码”
              渲染={({字段})=>(
                <表单项>
                  <FormLabel>密码</FormLabel>
                  <表单控件>
                    <输入类型=“密码”{...字段} />
                  </表单控件>
                  <表单消息/>
                </表单项>
              )}
            />
            <Button type="submit" className="w-full">登录</Button>
          </形式>
        </表格>
      ）
    }

**对话框/模态模式**
    
    
    导入{
      对话，
      对话内容，
      对话框描述，
      对话框页脚，
      对话框标题，
      对话框标题,
      对话触发器，
    来自 '@/components/ui/dialog'
    从 '@/components/ui/button' 导入 { Button }
    
    函数确认对话框({
      确认时，
      标题，
      描述
    }：{
      onConfirm: () => 无效
      标题：字符串
      描述：字符串
    }) {
      返回（
        <对话框>
          <DialogTrigger asChild>
            <按钮变体=“破坏性”>删除</按钮>
          </对话触发器>
          <对话内容>
            <对话框标题>
              <DialogTitle>{标题}</DialogTitle>
              <对话框描述>{描述}</对话框描述>
            </对话框标题>
            <对话框页脚>
              <按钮变体=“大纲”>取消</按钮>
              <按钮变体=“破坏性”onClick={onConfirm}>
                确认
              </按钮>
            </对话框页脚>
          </对话框内容>
        </对话框>
      ）
    }

**数据表与 Tanstack 表**
    
    
    导入{
      表，
      桌体，
      表格单元格，
      桌头，
      表头，
      表行，
    来自 '@/components/ui/table'
    导入{
      列定义，
      弹性渲染，
      获取CoreRowModel，
      使用ReactTable，
    来自“@tanstack/react-table”
    
    接口 DataTableProps<TData, TValue> {
      列：ColumnDef<TData, TValue>[]
      数据：TData[]
    }
    
    函数 DataTable<TData, TValue>({
      列，
      数据，
    }: DataTableProps<TData, TValue>) {
      常量表 = useReactTable({
        数据，
        列，
        获取CoreRowModel: getCoreRowModel(),
      })
    
      返回（
        <div className="rounded-md border">
          <表>
            <表头>
              {table.getHeaderGroups().map((headerGroup) => (
                <TableRow key={headerGroup.id}>
                  {headerGroup.headers.map((标题) => (
                    <TableHead key={header.id}>
                      {flex渲染（
                        header.column.columnDef.header，
                        header.getContext()
                      )}
                    </表头>
                  ))}
                </表行>
              ))}
            </表头>
            <表体>
              {table.getRowModel().rows.map((行) => (
                <TableRow key={row.id}>
                  {row.getVisibleCells().map((单元格) => (
                    <TableCell key={cell.id}>
                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
                    </表格单元格>
                  ))}
                </表行>
              ))}
            </表体>
          </表>
        </div>
      ）
    }

** **

## 6\.状态管理（中-高）

### 快速参考

* `state-local-first` \- 使用 useState/useReducer 作为本地状态
  * `state-context-static` \- 使用 Context 来处理不经常更改的数据
  * `state-衍生-计算` \- 计算衍生值，不存储它们
  * `state-url-state` \- 使用 URL 表示可共享/可添加书签的状态
  * `state-server-state` \- 使用 SWR/TanStack 查询服务器状态

### 关键原则

**避免派生状态**
    
    
    // 错误：存储派生状态
    函数 ProductList({ 产品 }) {
      const [items, setItems] = useState(产品)
      const [count, setCount] = useState(products.length) // 派生！
    
      // Bug：计数可能与项目不同步
    }
    
    // 正确：计算派生值
    函数 ProductList({ 产品 }) {
      const [items, setItems] = useState(产品)
      const count = items.length // 始终同步
    }

**过滤器/分页的 URL 状态**
    
    
    “使用客户端”
    
    从 'next/navigation' 导入 { useSearchParams, useRouter }
    
    函数产品过滤器（）{
      const searchParams = useSearchParams()
      常量路由器 = useRouter()
    
      const 类别 = searchParams.get('类别') || ‘全部’
    
      函数 setCategory(newCategory: 字符串) {
        const params = new URLSearchParams(searchParams)
        params.set('类别', newCategory)
        router.push(`?${params.toString()}`)
      }
    
      返回（
        <选择值={category} onValueChange={setCategory}>
          {/* 选项 */}
        </选择>
      ）
    }

** **

## 7\.动作和动画（中）

### 快速参考

*“运动目的”\-动画应该增强用户体验，而不是分散注意力
  * `motion-performance` \- 使用变换/不透明度，避免布局触发器
  * `motion-reduced-motion` \- 尊重更喜欢-reduced-motion
  * `motion-layout-id` \- 使用layoutId进行共享元素转换
  * `motion-exit-animations` \- 使用 AnimatePresence 进行退出动画
  * `motion-variants` \- 定义可重用的动画状态

### 安装
    
    
    npm 安装动作

### 核心原则

Motion（以前称为 Framer Motion）提供可增强用户体验的声明性动画。

**基本动画**
    
    
    “使用客户端”
    
    从“运动/反应”导入{运动}
    
    函数 FadeInCard({ 孩子 }: { 孩子: React.ReactNode }) {
      返回（
        <运动.div
          初始={{ 不透明度: 0, y: 20 }}
          动画={{ 不透明度: 1, y: 0 }}
          过渡={{持续时间:0.3}}
          className =“圆形-lg边框p-4”
        >
          {孩子}
        </motion.div>
      ）
    }

**交互状态**
    
    
    函数 InteractiveButton({ 孩子 }: { 孩子: React.ReactNode }) {
      返回（
        <动作.按钮
          whileHover={{ 比例: 1.02 }}
          whileTap={{ 比例: 0.98 }}
          过渡={{类型：'弹簧'，刚度：400，阻尼：17}}
          className =“px-4 py-2 bg-primary text-primary-foreground rounded-md”
        >
          {孩子}
        </motion.button>
      ）
    }

**使用 AnimatePresence 退出动画**
    
    
    从“运动/反应”导入{运动，AnimatePresence}
    
    函数NotificationList（{通知}：{通知：通知[]}）{
      返回（
        <动画存在>
          {notifications.map((通知) => (
            <运动.div
              键={通知.id}
              初始={{不透明度:0,x:50}}
              动画={{ 不透明度: 1, x: 0 }}
              退出={{ 不透明度: 0, x: -50 }}
              过渡={{持续时间:0.2}}
            >
              <通知数据={通知} />
            </motion.div>
          ))}
        </动画存在>
      ）
    }

**共享元素转换**
    
    
    函数 ProductGrid({ 产品 }: { 产品: 产品[] }) {
      const [selected, setSelected] = useState<产品 |空>(空)
    
      返回（
        <>
          <div className="网格 grid-cols-3 间隙-4">
            {产品.map((产品) => (
              <运动.div
                密钥={产品.id}
                layoutId={`产品-${product.id}`}
                onClick={() => setSelected(产品)}
                类名=“光标指针”
              >
                <img src={产品.image} alt={产品.名称} />
              </motion.div>
            ))}
          </div>
    
          <动画存在>
            {已选择&&(
              <运动.div
                layoutId={`产品-${selected.id}`}
                className =“固定插入-0弹性项目中心对齐中心”
              >
                <ProductDetail 产品={selected} onClose={() => setSelected(null)} />
              </motion.div>
            )}
          </动画存在>
        </>
      ）
    }

**可重复使用的变体**
    
    
    常量 fadeInUp = {
      初始：{ 不透明度：0，y：20 }，
      动画：{ 不透明度：1，y：0 }，
      退出：{ 不透明度：0，y：-20 }，
    }
    
    常量交错容器 = {
      动画：{
        过渡：{
          交错儿童：0.1，
        },
      },
    }
    
    函数 StaggeredList({ items }: { items: string[] }) {
      返回（
        <motion.ulvariants={staggerContainer}initial=“initial”animate=“animate”>
          {items.map((item, i) => (
            <motion.li 键={i} 变体={fadeInUp}>
              {项目}
            </motion.li>
          ))}
        </motion.ul>
      ）
    }

**滚动触发的动画**
    
    
    从“运动/反应”导入{运动，useInView}
    从 'react' 导入 { useRef }
    
    函数 ScrollReveal({ 孩子 }: { 孩子: React.ReactNode }) {
      常量 ref = useRef(null)
      const isInView = useInView(ref, { Once: true, margin: '-100px' })
    
      返回（
        <运动.div
          参考={参考}
          初始={{ 不透明度: 0, y: 50 }}
          动画={isInView？ { 不透明度: 1, y: 0 } : { 不透明度: 0, y: 50 }}
          过渡={{持续时间:0.5}}
        >
          {孩子}
        </motion.div>
      ）
    }

**尊重减少运动**
    
    
    从“运动/反应”导入{运动，useReducedMotion}
    
    函数 AccessibleAnimation({ 孩子 }: { 孩子: React.ReactNode }) {
      const shouldReduceMotion = useReducedMotion()
    
      返回（
        <运动.div
          初始={{不透明度：0，y：shouldReduceMotion？ 0 : 20 }}
          动画={{ 不透明度: 1, y: 0 }}
          过渡={{持续时间：shouldReduceMotion？ 0 : 0.3 }}
        >
          {孩子}
        </motion.div>
      ）
    }

### 性能提示

* 使用“transform”和“opacity”实现流畅的 60fps 动画
  * 为复杂的动画设置`willChange`属性
  * 保持退出动画较短（低于 300 毫秒）
  * 使用`useInView`来延迟加载动画
  * 避免直接对`width`、`height`、`top`、`left`进行动画处理

** **

## 8\.重新渲染优化（中）

### 快速参考

* `rerender-memo` \- 将昂贵的工作提取到记忆组件中
  * `rerender-usememo` \- 记住昂贵的计算
  * `rerender-usecallback` \- 稳定回调引用
  * `rerender-dependencies` \- 在效果中使用原始依赖关系
  * `rerender-transitions` \- 使用 startTransition 进行非紧急更新

### 关键原则

**昂贵组件的记忆**
    
    
    从“反应”导入{备忘录}
    
    const 昂贵列表 = 备忘录(函数 昂贵列表({
      项目
    }：{
      项目：项目[]
    }) {
      返回（
        <ul>
          {items.map(item => (
            <li key={item.id}>{/* 昂贵的渲染 */}</li>
          ))}
        </ul>
      ）
    })

**稳定回调**
    
    
    函数父级（）{
      const [计数，setCount] = useState(0)
    
      // 稳定引用 - 不会导致子进程重新渲染
      const handleClick = useCallback(() => {
        setCount(c => c + 1)
      }, [])
    
      返回 <MemoizedChild onClick={handleClick} />
    }

**带过渡的非紧急更新**
    
    
    函数搜索结果() {
      const [查询，setQuery] = useState('')
      const [结果，setResults] = useState([])
      const [isPending, startTransition] = useTransition()
    
      函数handleChange(e: React.ChangeEvent<HTMLInputElement>) {
        setQuery(e.target.value) // 紧急：立即更新输入
    
        开始转换(() => {
          setResults(filterResults(e.target.value)) // 非紧急：可以被中断
        })
      }
    
      返回（
        <>
          <输入值={query} onChange={handleChange} />
          {isPending && <微调器/>}
          <ResultsList 结果={结果} />
        </>
      ）
    }

** **

## 9\.辅助功能（中）

### 快速参考

* `a11y-semantic-html` \- 使用正确的 HTML 元素
  * `a11y-keyboard-nav` \- 确保键盘可导航性
  * `a11y-aria-labels` \- 为屏幕阅读器添加描述性标签
  * `a11y-focus-management` \- 管理模态和动态内容中的焦点
  * `a11y-color-contrast` \- 确保足够的色彩对比度

### 关键原则

**语义 HTML**
    
    
    // 错误：div 汤
    <div onClick={handleClick}>点我</div>
    
    // 正确：语义按钮
    <button onClick={handleClick}>点我</button>

**模态中的焦点管理**
    
    
    函数 Modal({ isOpen, onClose, 儿童 }) {
      const closeButtonRef = useRef<HTMLButtonElement>(null)
    
      使用效果（（）=> {
        如果（打开）{
          closeButtonRef.current?.focus()
        }
      }, [正在打开])
    
      返回（
        <对话框打开={isOpen} onOpenChange={onClose}>
          <对话内容>
            {孩子}
            <按钮 ref={closeButtonRef} onClick={onClose}>
              关闭
            </按钮>
          </对话框内容>
        </对话框>
      ）
    }

**跳过链接**
    
    
    函数布局({ 孩子 }) {
      返回（
        <>
          <一
            href="#主要内容"
            className="sr-only 焦点:not-sr-only 焦点:绝对焦点:top-4 焦点:left-4"
          >
            跳至主要内容
          </a>
          <标题/>
          <main id="main-content">{子项}</main>
        </>
      ）
    }

** **

## 10\. TypeScript 模式（中）

### 快速参考

* `ts-strict-mode` \- 启用严格的 TypeScript 配置
  * `ts-component-props` \- 定义显式的 prop 接口
  * `ts-generics` \- 对可重用组件使用泛型
  * `ts-discriminated-unions` \- 用于状态机
  * `ts-infer-when-possible` \- 让 TypeScript 在显而易见的情况下进行推断

### 关键原则

**组件道具**
    
    
    接口 ButtonProps 扩展 React.ButtonHTMLAttributes<HTMLButtonElement> {
      变体？： '默认' | '破坏性' | ‘大纲’
      尺寸？： 'sm' | 'md' | 'LG'
      正在加载？：布尔值
    }
    
    功能按钮({
      变体='默认'，
      大小='md'，
      正在加载，
      孩子们，
      残疾人,
      ...道具
    }: 按钮属性) {
      返回（
        <按钮
          禁用={禁用||正在加载}
          {...道具}
        >
          {正在加载？ <旋转器/>：孩子}
        </按钮>
      ）
    }

**国家受歧视工会**
    
    
    类型 AsyncState<T> =
      | { 状态： '空闲' }
      | { 状态： '正在加载' }
      | { 状态：'成功'；数据：T}
      | { 状态：'错误'；错误：错误}
    
    函数 useAsync<T>(asyncFn: () => Promise<T>) {
      const [state, setState] = useState<AsyncState<T>>({ status: 'idle' })
    
      // TypeScript 根据状态知道确切的形状
      if (state.status === '成功') {
        return state.data // TypeScript 知道数据存在
      }
    }

**通用组件**
    
    
    接口 SelectProps<T> {
      选项：T[]
      值：T
      onChange: (值: T) => void
      getLabel: (选项: T) => 字符串
      getValue: (选项: T) => 字符串
    }
    
    函数 Select<T>({ options, value, onChange, getLabel, getValue }: SelectProps<T>) {
      返回（
        <选择
          值={getValue(值)}
          onChange={(e) => {
            const selected = options.find(o => getValue(o) === e.target.value)
            if (已选择) onChange(已选择)
          }}
        >
          {options.map((选项) => (
            <选项键={getValue(选项)}值={getValue(选项)}>
              {获取标签（选项）}
            </选项>
          ))}
        </选择>
      ）
    }

** **

## React 19+ 功能

### 新钩子

**useActionState** \- 表单状态管理
    
    
    “使用客户端”
    
    从 'react' 导入 { useActionState }
    
    函数 SubscribeForm() {
      const [状态，formAction，isPending] = useActionState(
        异步（prevState，formData）=> {
          const email = formData.get('email')
          const 结果 = 等待订阅（电子邮件）
          返回结果
        },
        空
      ）
    
      返回（
        <表单操作={formAction}>
          <输入名称=“电子邮件”类型=“电子邮件”/>
          <按钮类型=“提交”禁用= {isPending}>
            {正在等待？ '订阅...' : '订阅'}
          </按钮>
          {状态？.error && <p className="text-red-500">{state.error}</p>}
        </形式>
      ）
    }

**useOptimistic** \- 乐观的 UI 更新
    
    
    “使用客户端”
    
    从 'react' 导入 { useOptimistic }
    
    函数 TodoList({ todos }: { todos: Todo[] }) {
      const [optimisticTodos, addOptimisticTodo] = useOptimistic(
        待办事项，
        （状态，newTodo：待办事项）=> [...状态，newTodo]
      ）
    
      异步函数 addTodo(formData: FormData) {
        const title = formData.get('title') 作为字符串
        const newTodo = { id: crypto.randomUUID(), title, 完成: false }
    
        addOptimisticTodo(newTodo) // 立即显示在 UI 中
        wait createTodo(title) // 然后持久化到服务器
      }
    
      返回（
        <>
          <表单操作={addTodo}>
            <输入名称=“标题”/>
            <按钮类型=“提交”>添加</按钮>
          </形式>
          <ul>
            {optimisticTodos.map(todo => (
              <li key={todo.id}>{todo.title}</li>
            ))}
          </ul>
        </>
      ）
    }

**使用** \- 异步资源读取
    
    
    从 'react' 导入 { use, Suspense }
    
    异步函数 fetchUser(id: string): Promise<User> {
      const res = 等待 fetch(`/api/users/${id}`)
      返回 res.json()
    }
    
    函数 UserProfile({ userPromise }: { userPromise: Promise<User> }) {
      const user = use(userPromise) // 挂起直至解决
      返回 <div>{用户名}</div>
    }
    
    函数页面({ userId }: { userId: string }) {
      const userPromise = fetchUser(userId)
    
      返回（
        <Suspense Fallback={<UserSkeleton />}>
          <UserProfile userPromise={userPromise} />
        </悬念>
      ）
    }

** **

## 项目结构
    
    
    源代码/
    ├── app/ # Next.js 应用路由器
    │ ├── 布局.tsx
    │ ├── 页.tsx
    │ └── (路线)/
    ├── 组件/
    │ ├── ui/ # shadcn/ui 组件
    │ │ ├── 按钮.tsx
    │ │ ├── 卡.tsx
    │ │ └── ...
    │ └── features/ # 特定功能组件
    │ ├── 授权/
    │ └── 仪表板/
    ├── hooks/ # 自定义钩子
    ├── lib/ # 实用程序
    │ ├── utils.ts # cn() 帮助器等
    │ └── validations.ts # Zod 模式
    ├── actions/ # 服务器动作
    └── types/ # TypeScript 类型

** **

## 参考文献

* [React 文档](<https://react.dev>)
  * [Next.js 文档](<https://nextjs.org>)
  * [shadcn/ui 文档](<https://ui.shadcn.com>)
  * [运动文档](<https://motion.dev>)
  * [Radix UI 基元](<https://radix-ui.com>)
  * [TanStack 查询](<https://tanstack.com/query>)
  * [Tailwind CSS](<https://tailwindcss.com>)</article></body></html>

反应最佳实践

包含技能