在 React 函数式组件中应用泛型

在 TypeScript 与 React 结合的开发场景中，我们经常会遇到需要让组件具备通用类型能力的需求。比如一个列表组件，既需要渲染用户列表，也需要渲染商品列表，不同列表的数据结构不同，但渲染逻辑高度相似。这时候就可以利用 TypeScript 的泛型，让函数式组件支持动态的类型参数，提升组件的复用性和类型安全性。

为什么函数式组件需要泛型

React 函数式组件本质是 JavaScript 函数，当我们用 TypeScript 开发时，如果直接给组件的 props 定义固定类型，会导致组件只能适配一种数据结构。例如一个展示列表的组件，如果 props 里的 list 被定义为 User[] 类型，那它就无法接收 Product[] 类型的数据，除非我们为每种数据类型单独写一个组件，这显然不符合复用原则。

泛型的作用就是让组件的类型参数化，我们在使用组件时再传入具体的类型，这样同一个组件就能适配多种不同的数据类型，同时 TypeScript 还能在编译阶段帮我们检查类型是否正确，避免运行时出现类型错误。

函数式组件泛型的基本用法

函数式组件的泛型定义方式和普通泛型函数类似，我们可以在组件函数名后面通过尖括号声明泛型参数，然后把泛型参数用到 props 的类型定义中。

下面是一个简单的泛型列表组件示例，它接收一个列表数据和渲染每一项的 render 函数作为 props：

import React from "react";

// 定义组件的 props 类型，T 是泛型参数
interface ListProps<T> {
  list: T[];
  // render 函数接收每一项数据，返回 React 节点
  render: (item: T, index: number) => React.ReactNode;
}

// 泛型函数式组件，声明泛型参数 T
function List<T>(props: ListProps<T>) {
  const { list, render } = props;
  return (
    <ul>
      {list.map((item, index) => (
        <li key={index}>{render(item, index)}</li>
      ))}
    </ul>
  );
}

export default List;

在这个示例中，我们定义了泛型参数 T，它代表列表中每一项的数据类型。ListProps<T> 里的 list 是 T[] 类型，render 函数的参数 item 也是 T 类型。这样当我们使用这个组件时，传入不同的数据类型，TypeScript 会自动推断 T 的具体类型。

泛型组件的使用示例

我们来看这个泛型列表组件的具体使用场景，首先定义两种不同的数据类型：

// 用户数据类型
interface User {
  id: number;
  name: string;
  age: number;
}

// 商品数据类型
interface Product {
  id: number;
  title: string;
  price: number;
}

然后在页面中使用 List 组件分别渲染用户列表和商品列表：

import React from "react";
import List from "./List";

// 用户列表数据
const userList: User[] = [
  { id: 1, name: "张三", age: 20 },
  { id: 2, name: "李四", age: 22 },
];

// 商品列表数据
const productList: Product[] = [
  { id: 1, title: "笔记本电脑", price: 5999 },
  { id: 2, title: "无线鼠标", price: 99 },
];

function App() {
  return (
    <div>
      <h3>用户列表</h3>
      {/* 传入用户列表，TypeScript 会自动推断 T 为 User 类型 */}
      <List
        list={userList}
        render={(item) => (
          <span>{item.name} - {item.age}岁</span>
        )}
      />

      <h3>商品列表</h3>
      {/* 传入商品列表，TypeScript 会自动推断 T 为 Product 类型 */}
      <List
        list={productList}
        render={(item) => (
          <span>{item.title} - ￥{item.price}</span>
        )}
      />
    </div>
  );
}

export default App;

从上面的使用示例可以看到，同一个 List 组件不需要做任何修改，就能同时适配 User 和 Product 两种数据类型。而且在 render 函数里，TypeScript 能正确提示 item 的属性，比如传入用户列表时，item 会有 name、age 属性，传入商品列表时，item 会有 title、price 属性，不会出现属性访问错误。

带默认类型的泛型组件

有时候我们希望泛型的类型有默认值，当用户没有显式传入类型时，使用默认类型。只需要在声明泛型参数时给 T 指定默认类型即可：

import React from "react";

// 定义默认数据类型
interface DefaultItem {
  id: number;
  label: string;
}

// 泛型参数 T 默认是 DefaultItem 类型
interface ListProps<T extends DefaultItem = DefaultItem> {
  list: T[];
  render: (item: T, index: number) => React.ReactNode;
}

function List<T extends DefaultItem = DefaultItem>(props: ListProps<T>) {
  const { list, render } = props;
  return (
    <ul>
      {list.map((item, index) => (
        <li key={item.id}>{render(item, index)}</li>
      ))}
    </ul>
  );
}

export default List;

在这个示例中，我们给泛型参数 T 设置了默认类型 DefaultItem，同时用 extends 约束了 T 必须是包含 id 和 label 属性的类型。如果用户使用组件时没有传入特定类型，组件会默认按照 DefaultItem 的类型处理，同时也能兼容符合约束的其他类型。

泛型组件的注意事项

• 泛型参数名通常使用单个大写字母，比如 T、U、K 等，这是 TypeScript 的通用约定，方便理解。
• 如果组件的 props 比较复杂，建议先把 props 的类型定义独立出来，比如上面的 ListProps<T>，这样代码结构更清晰。
• 泛型约束要合理，不要过度约束导致组件无法适配需要的类型，也不要没有约束导致类型检查失效。
• 如果组件同时使用了 forwardRef 或者 memo，泛型的写法会稍有不同，需要把泛型参数放到对应的类型定义中，避免类型推断错误。

总的来说，在 React 函数式组件中应用泛型，能大幅提升组件的通用性和类型安全性，是 TypeScript + React 开发中非常实用的技巧，适合用在需要适配多种数据结构的通用组件场景中。

React泛型组件TypeScript泛型函数式组件组件复用类型安全 本作品最后修改时间：2026-05-22 16:30:03