React / 系统课时
泛型组件设计
泛型组件设计
当列表、选择器和表格都要适配不同业务数据时,复制组件会迅速制造重复代码。本课用 TypeScript 泛型把“数据类型”交给调用方推导,让组件保持通用,同时让渲染函数、回调参数和列定义获得准确类型。
学习目标
- 理解泛型参数如何贯穿组件属性、渲染函数与事件回调
- 编写可自动推导类型的列表、选择器和表格组件
- 识别
any、过度约束和显式传参造成的类型退化
泛型组件解决什么问题
普通组件若把数据写死为 User[],只能服务用户页面;若改成 any[],虽然能复用,却会失去属性检查、自动补全和重构保护。泛型组件使用类型参数 T 表示“本次传入的数据项类型”,组件只规定如何遍历、取键和渲染,不预设业务字段。
类型参数应从 items、rows 等核心数据中自动推导,并继续传递到 renderItem、onChange、cell 等回调。这样,调用方一旦传入 User[],所有回调参数都会被识别为 User,无需重复写 <User>。

完成三个可推导组件
下面示例可直接放入 Vite React TypeScript 项目的 App.tsx。三个组件都使用函数声明,避免在 TSX 中把泛型箭头函数误解析为 JSX 标签。
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>
);
}预期结果
页面显示用户列表、用户下拉选择器和两列表格。
切换下拉选项后,“当前选择”同步更新为所选用户名。
在所有回调中输入 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>(...),语法更稳定,也更容易阅读。