React / 系统课时

泛型组件设计

泛型组件设计

当列表、选择器和表格都要适配不同业务数据时,复制组件会迅速制造重复代码。本课用 TypeScript 泛型把“数据类型”交给调用方推导,让组件保持通用,同时让渲染函数、回调参数和列定义获得准确类型。

学习目标

  • 理解泛型参数如何贯穿组件属性、渲染函数与事件回调
  • 编写可自动推导类型的列表、选择器和表格组件
  • 识别 any、过度约束和显式传参造成的类型退化

泛型组件解决什么问题

普通组件若把数据写死为 User[],只能服务用户页面;若改成 any[],虽然能复用,却会失去属性检查、自动补全和重构保护。泛型组件使用类型参数 T 表示“本次传入的数据项类型”,组件只规定如何遍历、取键和渲染,不预设业务字段。

类型参数应从 items、rows 等核心数据中自动推导,并继续传递到 renderItem、onChange、cell 等回调。这样,调用方一旦传入 User[],所有回调参数都会被识别为 User,无需重复写 <User>。

泛型参数在三个组件中的传递关系

完成三个可推导组件

下面示例可直接放入 Vite React TypeScript 项目的 App.tsx。三个组件都使用函数声明,避免在 TSX 中把泛型箭头函数误解析为 JSX 标签。

tsx
import { useState } from "react";
import type { ReactNode } from "react";

type ItemKey = string | number;

interface GenericListProps<T> {
  items: T[];
  getKey: (item: T) => ItemKey;
  renderItem: (item: T) => ReactNode;
}

function GenericList<T>({
  items,
  getKey,
  renderItem,
}: GenericListProps<T>) {
  return <ul>{items.map((item) => <li key={getKey(item)}>{renderItem(item)}</li>)}</ul>;
}

interface GenericSelectProps<T> {
  items: T[];
  selectedKey: string;
  getKey: (item: T) => string;
  getLabel: (item: T) => string;
  onChange: (item: T) => void;
}

function GenericSelect<T>({
  items,
  selectedKey,
  getKey,
  getLabel,
  onChange,
}: GenericSelectProps<T>) {
  return (
    <select
      value={selectedKey}
      onChange={(event) => {
        // select 的值始终是字符串,再映射回完整的 T 对象。
        const selected = items.find(
          (item) => getKey(item) === event.currentTarget.value,
        );
        if (selected) onChange(selected);
      }}
    >
      {items.map((item) => (
        <option key={getKey(item)} value={getKey(item)}>
          {getLabel(item)}
        </option>
      ))}
    </select>
  );
}

interface Column<T> {
  header: string;
  cell: (row: T) => ReactNode;
}

interface DataTableProps<T> {
  rows: T[];
  getKey: (row: T) => ItemKey;
  columns: Column<T>[];
}

function DataTable<T>({ rows, getKey, columns }: DataTableProps<T>) {
  return (
    <table>
      <thead>
        <tr>{columns.map((column) => <th key={column.header}>{column.header}</th>)}</tr>
      </thead>
      <tbody>
        {rows.map((row) => (
          <tr key={getKey(row)}>
            {columns.map((column) => (
              <td key={column.header}>{column.cell(row)}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

interface User {
  id: number;
  name: string;
  role: "admin" | "editor";
}

const initialUser: User = { id: 1, name: "Ada", role: "admin" };

const users: User[] = [
  initialUser,
  { id: 2, name: "Lin", role: "editor" },
];

const userColumns: Column<User>[] = [
  { header: "姓名", cell: (user) => user.name },
  { header: "角色", cell: (user) => user.role },
];

export default function App() {
  const [selectedUser, setSelectedUser] = useState(initialUser);

  return (
    <main>
      <h1>用户组件示例</h1>
      <GenericList
        items={users}
        getKey={(user) => user.id}
        renderItem={(user) => `${user.name}(${user.role})`}
      />
      <GenericSelect
        items={users}
        selectedKey={String(selectedUser.id)}
        getKey={(user) => String(user.id)}
        getLabel={(user) => user.name}
        onChange={setSelectedUser}
      />
      <p>当前选择:{selectedUser.name}</p>
      <DataTable rows={users} getKey={(user) => user.id} columns={userColumns} />
    </main>
  );
}

预期结果

text
页面显示用户列表、用户下拉选择器和两列表格。
切换下拉选项后,“当前选择”同步更新为所选用户名。
在所有回调中输入 user. 时,可获得 id、name、role 的类型提示。

保持类型推导的设计原则

优先让 T 从数据属性推导,而不是要求调用方每次写 <GenericList<User>>。只有当 TypeScript 无法从属性推断,或需要主动收窄联合类型时,才显式提供泛型参数。

组件应通过函数属性访问业务数据,例如 getKey、getLabel 和 cell。这种方式比强制 T 必须包含固定字段更灵活,也能避免为了满足组件约束而修改领域模型。

不要把回调参数写成 any,也不要在组件内部随意断言 as T。若组件确实只接受带 id 的对象,可以使用 T extends { id: ItemKey } 做最小约束;约束范围越大,可复用性越低。

在 TSX 中定义泛型箭头组件时,const List = <T,>(...) => ... 需要逗号消除 JSX 歧义。项目中更推荐使用 function List<T>(...),语法更稳定,也更容易阅读。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

泛型组件设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通