React 19 + TypeScript 完全指南 2026：新特性、最佳实践与项目实战

// 默认是 Server Component（不需要 'use client'）
export default function BlogPosts() {
  // 直接在组件中获取数据
  const posts = await db.posts.findMany();

  return (
    <div>
      <h1>博客文章</h1>
      {posts.map((post) => (
        <PostCard key={post.id} post={post} />
      ))}
    </div>
  );
}

// Client Component 需要 'use client' 指令
'use client';

import { useState } from 'react';

export function LikeButton({ postId }: { postId: string }) {
  const [likes, setLikes] = useState(0);

  return (
    <button onClick={() => setLikes(likes + 1)}>
      👍 {likes}
    </button>
  );
}

// Server Action（在 Server Component 中定义）
async function updateName(formData: FormData) {
  'use server';
  
  const name = formData.get('name') as string;
  await db.user.update({ name });
}

export default function Profile() {
  return (
    <form action={updateName}>
      <input type="text" name="name" />
      <button type="submit">更新</button>
    </form>
  );
}

'use client';

import { useActionState } from 'react';

async function updateName(prevState: { error?: string }, formData: FormData) {
  'use server';
  
  const name = formData.get('name') as string;
  
  if (name.length < 2) {
    return { error: '名字太短了' };
  }
  
  await db.user.update({ name });
  return { error: undefined };
}

export default function ProfileForm() {
  const [state, formAction, isPending] = useActionState(updateName, {});

  return (
    <form action={formAction}>
      <input type="text" name="name" />
      {state.error && <p style={{ color: 'red' }}>{state.error}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? '更新中...' : '更新'}
      </button>
    </form>
  );
}

'use client';

import { useOptimistic, useState } from 'react';

type Message = {
  id: string;
  text: string;
  sending?: boolean;
};

async function sendMessage(text: string): Promise<Message> {
  // 模拟 API 调用
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return { id: Date.now().toString(), text };
}

export function Chat() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [optimisticMessages, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: string) => [
      ...state,
      { id: 'temp', text: newMessage, sending: true },
    ]
  );

  async function handleSubmit(formData: FormData) {
    const text = formData.get('message') as string;
    addOptimistic(text);
    
    const message = await sendMessage(text);
    setMessages((prev) => [...prev, message]);
  }

  return (
    <div>
      <div>
        {optimisticMessages.map((msg) => (
          <div key={msg.id} style={{ opacity: msg.sending ? 0.5 : 1 }}>
            {msg.text} {msg.sending && '发送中...'}
          </div>
        ))}
      </div>
      <form action={handleSubmit}>
        <input type="text" name="message" />
        <button type="submit">发送</button>
      </form>
    </div>
  );
}

import { use } from 'react';

// 读取 Promise
function UserProfile({ userId }: { userId: string }) {
  const user = use(fetchUser(userId)); // 自动处理 Suspense
  
  return <div>{user.name}</div>;
}

// 读取 Context
function ThemeButton() {
  const theme = use(ThemeContext);
  
  return <button style={{ background: theme.primary }}>按钮</button>;
}

// 配合 Suspense 使用
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

// 之前：初始值只在第一次渲染时计算，但语法不直观
const ref = useRef(createExpensiveObject());

// React 19：支持函数初始化，只执行一次
const ref = useRef(() => createExpensiveObject());

// 之前：forwardRef
const MyInput = forwardRef((props, ref) => {
  return <input ref={ref} {...props} />;
});

// React 19：直接接收 ref prop
function MyInput({ ref, ...props }) {
  return <input ref={ref} {...props} />;
}

// 之前：清理函数不接收参数
useEffect(() => {
  const controller = new AbortController();
  fetchData(controller.signal);
  return () => controller.abort();
}, []);

// React 19：清理函数可以接收一个参数（表示为什么清理）
useEffect(() => {
  // ...
  return (reason) => {
    console.log('Cleanup reason:', reason); // 'unmount' | 'replay' | 'dep-change'
  };
}, []);

interface ButtonProps {
  text: string;
  onClick?: () => void;
  variant?: 'primary' | 'secondary' | 'danger';
  disabled?: boolean;
}

function Button({ 
  text, 
  onClick, 
  variant = 'primary', 
  disabled = false 
}: ButtonProps) {
  return (
    <button 
      onClick={onClick} 
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {text}
    </button>
  );
}

import type { ButtonHTMLAttributes } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
  loading?: boolean;
}

function Button({ 
  variant = 'primary', 
  loading = false,
  children,
  disabled,
  ...props 
}: ButtonProps) {
  return (
    <button 
      className={`btn btn-${variant}`}
      disabled={disabled || loading}
      {...props}
    >
      {loading && <Spinner />}
      {children}
    </button>
  );
}

import type { ReactNode } from 'react';

interface CardProps {
  title: string;
  children: ReactNode;
  footer?: ReactNode;
}

function Card({ title, children, footer }: CardProps) {
  return (
    <div className="card">
      <h3>{title}</h3>
      <div className="card-body">{children}</div>
      {footer && <div className="card-footer">{footer}</div>}
    </div>
  );
}

// TypeScript 会自动推断类型
const [count, setCount] = useState(0); // number
const [name, setName] = useState(''); // string
const [user, setUser] = useState({ name: 'Tom', age: 20 }); // { name: string; age: number }

interface User {
  id: string;
  name: string;
  email: string;
}

// 可能为 null
const [user, setUser] = useState<User | null>(null);

// 可能为 undefined
const [selectedId, setSelectedId] = useState<string | undefined>();

interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

const [todos, setTodos] = useState<Todo[]>([]);

function toggleTodo(id: string) {
  setTodos((prev) =>
    prev.map((todo) =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    )
  );
}

interface TodoState {
  todos: Todo[];
  filter: 'all' | 'active' | 'completed';
}

type TodoAction =
  | { type: 'ADD_TODO'; payload: string }
  | { type: 'TOGGLE_TODO'; payload: string }
  | { type: 'DELETE_TODO'; payload: string }
  | { type: 'SET_FILTER'; payload: TodoState['filter'] };

function todoReducer(state: TodoState, action: TodoAction): TodoState {
  switch (action.type) {
    case 'ADD_TODO':
      return {
        ...state,
        todos: [...state.todos, { id: Date.now().toString(), text: action.payload, completed: false }],
      };
    case 'TOGGLE_TODO':
      return {
        ...state,
        todos: state.todos.map((todo) =>
          todo.id === action.payload ? { ...todo, completed: !todo.completed } : todo
        ),
      };
    case 'DELETE_TODO':
      return {
        ...state,
        todos: state.todos.filter((todo) => todo.id !== action.payload),
      };
    case 'SET_FILTER':
      return { ...state, filter: action.payload };
    default:
      return state;
  }
}

function TodoApp() {
  const [state, dispatch] = useReducer(todoReducer, {
    todos: [],
    filter: 'all',
  });
  // ...
}

import { createContext, useContext, useState, type ReactNode } from 'react';

interface Theme {
  primary: string;
  secondary: string;
  mode: 'light' | 'dark';
}

interface ThemeContextType {
  theme: Theme;
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>({
    primary: '#007bff',
    secondary: '#6c757d',
    mode: 'light',
  });

  const toggleTheme = () => {
    setTheme((prev) => ({
      ...prev,
      mode: prev.mode === 'light' ? 'dark' : 'light',
    }));
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

// 使用
function MyComponent() {
  const { theme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>切换主题</button>;
}

import { useState, useEffect } from 'react';

interface UseFetchResult<T> {
  data: T | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

function useFetch<T>(url: string): UseFetchResult<T> {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  const fetchData = async () => {
    setLoading(true);
    setError(null);
    try {
      const res = await fetch(url);
      const json = await res.json();
      setData(json);
    } catch (e) {
      setError(e as Error);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchData();
  }, [url]);

  return { data, loading, error, refetch: fetchData };
}

// 使用
function UserProfile({ userId }: { userId: string }) {
  const { data: user, loading, error } = useFetch<User>(`/api/users/${userId}`);
  
  if (loading) return <div>加载中...</div>;
  if (error) return <div>出错了：{error.message}</div>;
  if (!user) return <div>用户不存在</div>;
  
  return <div>{user.name}</div>;
}

import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface Bear {
  id: string;
  name: string;
}

interface BearState {
  bears: Bear[];
  addBear: (name: string) => void;
  removeBear: (id: string) => void;
  clearBears: () => void;
}

const useBearStore = create<BearState>()(
  devtools(
    persist(
      (set) => ({
        bears: [],
        addBear: (name) =>
          set((state) => ({
            bears: [...state.bears, { id: Date.now().toString(), name }],
          })),
        removeBear: (id) =>
          set((state) => ({
            bears: state.bears.filter((bear) => bear.id !== id),
          })),
        clearBears: () => set({ bears: [] }),
      }),
      { name: 'bear-storage' }
    )
  )
);

// 使用
function BearCounter() {
  const bears = useBearStore((state) => state.bears);
  return <h1>{bears.length} 只熊</h1>;
}

function BearControls() {
  const addBear = useBearStore((state) => state.addBear);
  const removeBear = useBearStore((state) => state.removeBear);
  
  return (
    <div>
      <button onClick={() => addBear('新熊')}>添加熊</button>
    </div>
  );
}

import { 
  useQuery, 
  useMutation, 
  useQueryClient,
  type UseQueryResult 
} from '@tanstack/react-query';

interface User {
  id: string;
  name: string;
  email: string;
}

// 查询 Hook
function useUser(userId: string): UseQueryResult<User, Error> {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: async () => {
      const res = await fetch(`/api/users/${userId}`);
      if (!res.ok) throw new Error('获取用户失败');
      return res.json();
    },
    enabled: !!userId,
    staleTime: 5 * 60 * 1000, // 5 分钟内视为新鲜
  });
}

// 变更 Hook
function useUpdateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async ({ userId, data }: { userId: string; data: Partial<User> }) => {
      const res = await fetch(`/api/users/${userId}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });
      if (!res.ok) throw new Error('更新失败');
      return res.json();
    },
    onSuccess: (data, variables) => {
      // 自动更新缓存
      queryClient.setQueryData(['user', variables.userId], data);
    },
  });
}

// 使用
function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useUser(userId);
  const updateUser = useUpdateUser();
  
  if (isLoading) return <div>加载中...</div>;
  if (error) return <div>出错了</div>;
  if (!user) return <div>用户不存在</div>;
  
  return (
    <div>
      <h1>{user.name}</h1>
      <button 
        onClick={() => updateUser.mutate({ userId, data: { name: '新名字' } })}
      >
        更新
      </button>
    </div>
  );
}

import { memo } from 'react';

interface TodoItemProps {
  todo: Todo;
  onToggle: (id: string) => void;
}

// 只有当 props 变化时才重新渲染
const TodoItem = memo(function TodoItem({ todo, onToggle }: TodoItemProps) {
  console.log('TodoItem 渲染');
  return (
    <div>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={() => onToggle(todo.id)}
      />
      {todo.text}
    </div>
  );
});

import { useCallback, useState } from 'react';

function TodoList() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [filter, setFilter] = useState<'all' | 'active' | 'completed'>('all');

  // 只有 todos 变化时才重新创建函数
  const handleToggle = useCallback((id: string) => {
    setTodos((prev) =>
      prev.map((todo) =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      )
    );
  }, []); // 空依赖，函数永远不变

  const filteredTodos = todos.filter((todo) => {
    if (filter === 'all') return true;
    if (filter === 'active') return !todo.completed;
    return todo.completed;
  });

  return (
    <div>
      {filteredTodos.map((todo) => (
        <TodoItem key={todo.id} todo={todo} onToggle={handleToggle} />
      ))}
    </div>
  );
}

import { useMemo } from 'react';

function TodoStats({ todos }: { todos: Todo[] }) {
  // 只有 todos 变化时才重新计算
  const stats = useMemo(() => {
    console.log('计算统计数据');
    const total = todos.length;
    const completed = todos.filter((t) => t.completed).length;
    const active = total - completed;
    const completionRate = total > 0 ? (completed / total) * 100 : 0;
    
    return { total, completed, active, completionRate };
  }, [todos]);

  return (
    <div>
      <p>总计：{stats.total}</p>
      <p>已完成：{stats.completed}</p>
      <p>进行中：{stats.active}</p>
      <p>完成率：{stats.completionRate.toFixed(1)}%</p>
    </div>
  );
}

// ✅ 好：使用唯一 ID
{todos.map((todo) => (
  <TodoItem key={todo.id} todo={todo} />
))}

// ❌ 不好：使用索引（当列表顺序会变化时）
{todos.map((todo, index) => (
  <TodoItem key={index} todo={todo} />
))}

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

function LongList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    overscan: 5,
  });

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

import { lazy, Suspense } from 'react';

// 动态导入组件
const HeavyComponent = lazy(() => import('./HeavyComponent'));
const Dashboard = lazy(() => import('./Dashboard'));

function App() {
  return (
    <div>
      <h1>我的应用</h1>
      <Suspense fallback={<Loading />}>
        <HeavyComponent />
      </Suspense>
      
      <Suspense fallback={<Loading />}>
        <Dashboard />
      </Suspense>
    </div>
  );
}

// 路由级代码分割
import { Routes, Route } from 'react-router-dom';

const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));

function AppRouter() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        <Route path="/dashboard" element={<Dashboard />} />
      </Routes>
    </Suspense>
  );
}

// 1. 导入
import { useState, useCallback } from 'react';

// 2. 类型定义
interface UserCardProps {
  user: User;
  onEdit?: (user: User) => void;
}

// 3. 组件函数
export function UserCard({ user, onEdit }: UserCardProps) {
  // 4. State
  const [isEditing, setIsEditing] = useState(false);
  
  // 5. 计算属性
  const fullName = `${user.firstName} ${user.lastName}`;
  
  // 6. 事件处理
  const handleEdit = useCallback(() => {
    setIsEditing(true);
    onEdit?.(user);
  }, [user, onEdit]);
  
  // 7. 渲染
  return (
    <div className="user-card">
      <h3>{fullName}</h3>
      <p>{user.email}</p>
      <button onClick={handleEdit}>编辑</button>
    </div>
  );
}

// 8. 默认导出
export default UserCard;

// ✅ 好的命名
interface User {
  id: string;
  name: string;
}

type UserRole = 'admin' | 'editor' | 'viewer';

type ApiResponse<T> = {
  data: T;
  success: boolean;
  message: string;
};

// ❌ 不好的命名
interface IUser {}     // 不要加 I 前缀
type user = {};        // 用 PascalCase
type UserType = {};    // 避免 Type 后缀（除非必要）

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:jsx-a11y/recommended",
    "prettier"
  ],
  "rules": {
    "react/react-in-jsx-scope": "off",
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-explicit-any": "warn",
    "react/prop-types": "off"
  },
  "settings": {
    "react": {
      "version": "detect"
    }
  }
}

// 1. 使用 unknown 代替 any
function processValue(value: unknown) {
  if (typeof value === 'string') {
    // 这里 value 被收窄为 string
    console.log(value.toUpperCase());
  }
}

// 2. 使用类型守卫
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value
  );
}

// 3. 使用泛型
function identity<T>(value: T): T {
  return value;
}

// ❌ 问题：count 总是初始值
useEffect(() => {
  const timer = setInterval(() => {
    console.log(count); // 闭包捕获了初始值
  }, 1000);
  return () => clearInterval(timer);
}, []); // 空依赖

// ✅ 解决方案：使用函数式更新
useEffect(() => {
  const timer = setInterval(() => {
    setCount((prev) => prev + 1);
  }, 1000);
  return () => clearInterval(timer);
}, []);

// ❌ 问题：刚设置完就读取不到新值
setCount(count + 1);
console.log(count); // 还是旧值

// ✅ 解决方案：使用 useEffect 监听变化
useEffect(() => {
  console.log('count 变化了：', count);
}, [count]);

// ❌ ESLint 警告：缺少依赖
useEffect(() => {
  fetchData(userId);
}, []); // 警告：缺少 userId

// ✅ 解决方案 1：添加依赖（推荐）
useEffect(() => {
  fetchData(userId);
}, [userId]);

// ✅ 解决方案 2：用 useCallback/useMemo 稳定函数
const fetchUserData = useCallback(() => {
  fetchData(userId);
}, [userId]);

useEffect(() => {
  fetchUserData();
}, [fetchUserData]);

// React Hook Form + Zod 示例
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(2, '名字至少 2 个字符'),
  email: z.string().email('请输入有效的邮箱'),
  age: z.number().min(18, '必须年满 18 岁').optional(),
});

type FormData = z.infer<typeof schema>;

function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  const onSubmit = (data: FormData) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <input {...register('name')} placeholder="姓名" />
        {errors.name && <p>{errors.name.message}</p>}
      </div>
      <div>
        <input {...register('email')} placeholder="邮箱" />
        {errors.email && <p>{errors.email.message}</p>}
      </div>
      <button type="submit">提交</button>
    </form>
  );
}