React从基础入门到高级实战：React 核心技术 - React 与 TypeScript：构建类型安全的应用

React 与 TypeScript：构建类型安全的应用

在现代前端开发中，TypeScript 因其强大的类型系统和编译时错误检查功能，已成为 React 开发者的热门选择。通过为代码添加类型定义，TypeScript 能够显著提升代码的健壮性、可维护性和团队协作效率，同时减少运行时错误。本教程面向希望提升代码质量的开发者，旨在帮助你从零开始掌握 React 与 TypeScript 的结合使用。

本文将从项目配置入手，深入探讨 Props、State 和事件的类型定义，讲解类型安全的 Hooks 和 Context 的实现方法，并解决处理第三方库类型时的常见问题。此外，我将通过一个类型安全的用户管理组件案例展示实际应用，并提供一个练习任务（为现有项目添加 TypeScript 支持），帮助你将所学知识运用到实践中。最后，我会分享 TypeScript 的渐进式引入策略，确保你能无缝过渡到类型化开发。

---

文章目标

• 掌握 React + TypeScript 项目的配置和初始化。
• 学会为 Props、State 和事件定义类型，确保类型安全。
• 实现类型安全的 Hooks 和 Context，提升代码可靠性。
• 解决第三方库类型支持的常见问题。
• 通过用户管理组件案例和练习任务，巩固所学内容。
• 了解 TypeScript 的渐进式引入策略，实现平滑迁移。

---

1. 配置 React + TypeScript 项目

1.1 为什么选择 TypeScript？

TypeScript 是 JavaScript 的超集，增加了可选的静态类型系统，使开发者能够在代码编写阶段捕获潜在错误。其主要优势包括：

• 编译时错误检查：在运行前发现类型问题，减少 bug。
• 智能提示和自动补全：提升开发效率，尤其是在大型项目中。
• 代码可维护性：类型定义作为文档，便于理解和维护。
• 生态支持：React 官方和社区对 TypeScript 的支持日益完善。

1.2 创建项目

我们可以使用 Vite 或 Create React App（CRA）快速搭建 React + TypeScript 项目。以下是两种方式的详细步骤：

使用 Vite（推荐）

Vite 是一个现代化的构建工具，启动速度快、热更新高效，非常适合 TypeScript 项目。

npm create vite@latest my-react-ts-app -- --template react-ts
cd my-react-ts-app
npm install
npm run dev

• --template react-ts：指定 React + TypeScript 模板。
• 项目启动后，默认会在 localhost:5173 上运行。

使用 Create React App

CRA 是 React 官方提供的脚手架工具，支持 TypeScript。

npx create-react-app my-react-ts-app --template typescript
cd my-react-ts-app
npm start

• --template typescript：启用 TypeScript 支持。
• 项目默认运行在 localhost:3000。

1.3 项目结构

React + TypeScript 项目的结构与普通 React 项目类似，但文件扩展名有所不同：

my-react-ts-app/
├── src/
│   ├── App.tsx          # 主组件（含 JSX）
│   ├── index.tsx        # 入口文件
│   ├── components/      # 组件目录
│   │   └── UserList.tsx
│   └── types/           # 类型定义目录
│       └── user.ts
├── tsconfig.json        # TypeScript 配置文件
├── package.json
└── ...

• .tsx：包含 JSX 的 TypeScript 文件。
• .ts：纯 TypeScript 文件。
• tsconfig.json：配置 TypeScript 编译选项，如严格模式、模块解析等。

示例 tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "module": "esnext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

• "strict": true：启用严格类型检查，推荐初学者开启以养成良好习惯。

---

2. 类型定义：Props、State、事件

类型定义是 React + TypeScript 应用的核心，确保组件的输入和状态符合预期。

2.1 Props 类型定义

Props 是组件的外部接口，通过类型定义可以避免传入错误的数据。

基本类型

interface UserProps {
  name: string;
  age: number;
  isAdmin?: boolean; // 可选属性
}

function User({ name, age, isAdmin }: UserProps) {
  return (
    <div>
      <p>姓名: {name}</p>
      <p>年龄: {age}</p>
      {isAdmin && <p>管理员</p>}
    </div>
  );
}

• interface：定义 Props 的结构。
• ?：表示可选属性，未提供时值为 undefined。

传递子组件

interface LayoutProps {
  children: React.ReactNode;
}

function Layout({ children }: LayoutProps) {
  return <div className="layout">{children}</div>;
}

• React.ReactNode：表示子节点类型，可以是字符串、数字、JSX 元素等。

传递函数

interface ButtonProps {
  label: string;
  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
}

function Button({ label, onClick }: ButtonProps) {
  return <button onClick={onClick}>{label}</button>;
}

• React.MouseEvent<HTMLButtonElement>：React 提供的鼠标事件类型。

2.2 State 类型定义

State 是组件的内部状态，TypeScript 可以通过泛型或类型推断定义其类型。

useState

import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState<number>(0);
  return (
    <div>
      <p>计数: {count}</p>
      <button onClick={() => setCount(count + 1)}>增加</button>
    </div>
  );
}

• useState<number>(0)：显式指定 count 为数字类型。

复杂 State

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

function UserProfile() {
  const [user, setUser] = useState<User | null>(null);
  return (
    <div>
      {user ? (
        <p>欢迎, {user.name}</p>
      ) : (
        <p>请登录</p>
      )}
      <button onClick={() => setUser({ id: 1, name: '张三' })}>登录</button>
    </div>
  );
}

• User | null：表示 user 可以是 User 类型或 null。

useReducer

interface State {
  count: number;
}

type Action = { type: 'increment' } | { type: 'decrement' };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'increment':
      return { count: state.count + 1 };
    case 'decrement':
      return { count: state.count - 1 };
    default:
      return state;
  }
}

function Counter() {
  const [state, dispatch] = useReducer(reducer, { count: 0 });
  return (
    <div>
      <p>计数: {state.count}</p>
      <button onClick={() => dispatch({ type: 'increment' })}>增加</button>
      <button onClick={() => dispatch({ type: 'decrement' })}>减少</button>
    </div>
  );
}

• type Action：使用联合类型定义动作类型。

2.3 事件类型定义

React 提供了类型化的合成事件，确保事件处理函数接收正确的参数。

鼠标事件

function handleClick(event: React.MouseEvent<HTMLButtonElement>) {
  console.log('点击位置:', event.clientX, event.clientY);
}

表单事件

function handleChange(event: React.ChangeEvent<HTMLInputElement>) {
  console.log('输入值:', event.target.value);
}

function Form() {
  return <input type="text" onChange={handleChange} />;
}

键盘事件

function handleKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
  if (event.key === 'Enter') {
    console.log('按下 Enter 键');
  }
}

• React 的事件类型以 React. 开头，后接具体事件类型和目标元素。

---

3. 类型安全的 Hooks 和 Context

Hooks 和 Context 是 React 的核心特性，TypeScript 可以增强它们的安全性和可预测性。

3.1 类型安全的 Hooks

useState

interface User {
  name: string;
  age: number;
}

function UserForm() {
  const [user, setUser] = useState<User>({ name: '', age: 0 });
  return (
    <div>
      <input
        value={user.name}
        onChange={(e) => setUser({ ...user, name: e.target.value })}
      />
      <input
        type="number"
        value={user.age}
        onChange={(e) => setUser({ ...user, age: +e.target.value })}
      />
    </div>
  );
}

useEffect

interface Data {
  id: number;
  title: string;
}

function DataFetcher() {
  const [data, setData] = useState<Data | null>(null);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch('/api/data');
      const result: Data = await response.json();
      setData(result);
    };
    fetchData();
  }, []);

  return <div>{data?.title || '加载中...'}</div>;
}

自定义 Hook

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

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch(url);
      const result: T = await response.json();
      setData(result);
      setLoading(false);
    };
    fetchData();
  }, [url]);

  return { data, loading };
}

function App() {
  const { data, loading } = useFetch<{ id: number; name: string }>('/api/user');
  return <div>{loading ? '加载中...' : data?.name}</div>;
}

• T：泛型参数，允许 Hook 处理任意类型的数据。

3.2 类型安全的 Context

Context 用于全局状态管理，TypeScript 可以确保其类型安全。

创建 Context

interface ThemeContextType {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
}

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

提供 Context

function App() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');
  const toggleTheme = () => setTheme((prev) => (prev === 'light' ? 'dark' : 'light'));

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

消费 Context

function Toolbar() {
  const context = useContext(ThemeContext);
  if (!context) throw new Error('ThemeContext 必须在 ThemeProvider 中使用');
  const { theme, toggleTheme } = context;
  return (
    <div>
      <p>当前主题: {theme}</p>
      <button onClick={toggleTheme}>切换主题</button>
    </div>
  );
}

• undefined 默认值：强制开发者在使用 useContext 时检查上下文是否存在。

---

4. 处理第三方库的类型

第三方库的类型支持是 TypeScript 应用中的常见挑战，以下是应对策略：

4.1 官方类型支持

许多库（如 react-router-dom、axios）内置类型定义，安装即可使用。

npm install axios

4.2 DefinitelyTyped

社区维护的 @types 包为未提供官方类型的库补充支持：

npm install --save-dev @types/lodash

4.3 自定义类型

若无现成类型，可手动声明：

declare module 'my-library' {
  export function doSomething(param: string): number;
}

• 保存为 .d.ts 文件（如 types/my-library.d.ts）。

4.4 临时跳过类型检查

在类型缺失且时间紧迫时，可使用 any：

const library: any = require('my-library');

• 注意 ：尽量避免长期依赖 any，应尽快补充类型。

---

5. 案例：类型安全的用户管理组件

以下是一个类型安全的用户管理组件，展示如何将类型定义应用到实际开发中。

5.1 定义类型

interface User {
  id: number;
  name: string;
  email: string;
  isAdmin: boolean;
}

interface UserListProps {
  users: User[];
  onDelete: (id: number) => void;
}

interface UserListItemProps {
  user: User;
  onDelete: (id: number) => void;
}

5.2 组件实现

function UserList({ users, onDelete }: UserListProps) {
  return (
    <ul>
      {users.map((user) => (
        <UserListItem key={user.id} user={user} onDelete={onDelete} />
      ))}
    </ul>
  );
}

function UserListItem({ user, onDelete }: UserListItemProps) {
  return (
    <li>
      <p>姓名: {user.name}</p>
      <p>邮箱: {user.email}</p>
      <p>角色: {user.isAdmin ? '管理员' : '普通用户'}</p>
      <button onClick={() => onDelete(user.id)}>删除</button>
    </li>
  );
}

5.3 使用组件

function App() {
  const [users, setUsers] = useState<User[]>([
    { id: 1, name: '张三', email: '[email protected]', isAdmin: true },
    { id: 2, name: '李四', email: '[email protected]', isAdmin: false },
  ]);

  const handleDelete = (id: number) => {
    setUsers(users.filter((user) => user.id !== id));
  };

  return <UserList users={users} onDelete={handleDelete} />;
}

• 类型安全：所有 Props 和 State 都有明确类型，编译器会检查错误。
• 可扩展性：类型定义清晰，便于后续添加功能。

---

6. 练习：为现有项目添加 TypeScript 支持

将现有 JavaScript React 项目迁移到 TypeScript 是一项实用技能，以下是具体步骤和策略。

6.1 安装 TypeScript

npm install --save-dev typescript @types/react @types/react-dom

6.2 配置 tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

6.3 逐步迁移

1. 重命名文件 ：将 .js 文件改为 .tsx（含 JSX）或 .ts（无 JSX）。
2. 添加类型：为 Props、State 和事件定义类型。
3. 修复错误：根据 TypeScript 编译器的提示修复问题。

示例迁移

原始 JavaScript：

function User({ name, age }) {
  return (
    <div>
      <p>{name}</p>
      <p>{age}</p>
    </div>
  );
}

迁移后 TypeScript：

interface UserProps {
  name: string;
  age: number;
}

function User({ name, age }: UserProps) {
  return (
    <div>
      <p>{name}</p>
      <p>{age}</p>
    </div>
  );
}

6.4 渐进式引入策略

• 从小处入手：从简单组件开始迁移，逐步扩展到复杂部分。
• 临时使用 any ：在类型复杂时可用 any，后续优化。
• 工具辅助：利用 VS Code 的 TypeScript 插件快速发现和修复问题。
• 分阶段提交：每次迁移少量代码，提交到版本控制，确保可回滚。

---

7. 总结与进阶建议

本文全面介绍了 React 与 TypeScript 的结合应用，从项目配置到类型定义，再到实际案例和迁移策略，帮助你构建健壮的 React 应用。

总结

• 项目配置：Vite 和 CRA 提供便捷的 TypeScript 支持。
• 类型定义：Props、State 和事件类型化是核心。
• Hooks 和 Context：类型安全提升代码可靠性。
• 第三方库：多种策略应对类型缺失问题。
• 实践：通过案例和练习掌握实际应用。

进阶建议

• 深入学习 TypeScript 高级特性，如泛型、类型守卫和条件类型。
• 在实际项目中尝试类型化 Redux 或其他状态管理库。

---

以下是一个完整的 React + TypeScript 示例应用，包含用户管理功能，可直接运行：

<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>React + TypeScript 用户管理</title>
  <script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.development.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.development.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/@babel/standalone@7/babel.min.js"></script>
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
  <div id="root" class="p-4"></div>
  <script type="text/babel" data-type="module">
    const { useState } = React;

    // 类型定义
    interface User {
      id: number;
      name: string;
      email: string;
      isAdmin: boolean;
    }

    interface UserListProps {
      users: User[];
      onDelete: (id: number) => void;
    }

    interface UserListItemProps {
      user: User;
      onDelete: (id: number) => void;
    }

    // 组件实现
    function UserList({ users, onDelete }: UserListProps) {
      return (
        <ul className="space-y-4">
          {users.map((user) => (
            <UserListItem key={user.id} user={user} onDelete={onDelete} />
          ))}
        </ul>
      );
    }

    function UserListItem({ user, onDelete }: UserListItemProps) {
      return (
        <li className="p-4 bg-gray-100 rounded-lg shadow">
          <p className="font-bold">姓名: {user.name}</p>
          <p>邮箱: {user.email}</p>
          <p>角色: {user.isAdmin ? '管理员' : '普通用户'}</p>
          <button
            className="mt-2 px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
            onClick={() => onDelete(user.id)}
          >
            删除
          </button>
        </li>
      );
    }

    function App() {
      const [users, setUsers] = useState<User[]>([
        { id: 1, name: '张三', email: '[email protected]', isAdmin: true },
        { id: 2, name: '李四', email: '[email protected]', isAdmin: false },
      ]);

      const handleDelete = (id: number) => {
        setUsers(users.filter((user) => user.id !== id));
      };

      return (
        <div className="max-w-2xl mx-auto">
          <h1 className="text-2xl font-bold mb-4">用户管理</h1>
          <UserList users={users} onDelete={handleDelete} />
        </div>
      );
    }

    // 渲染
    ReactDOM.render(<App />, document.getElementById('root'));
  </script>
</body>
</html>

只需将上述代码保存为 index.html 并在浏览器中打开，即可看到一个类型安全的用户管理应用。祝你学习愉快！