如何基于react-hook-form创建可控通用TextField组件？

核心问题分析 #

你遇到的Type 'keyof T' is not assignable to type 'Path<T>'错误，本质是keyof T仅能表示表单对象的顶层键名，而React Hook Form的Controller要求的name参数是FieldPath<T>类型——该类型支持嵌套字段路径（如'user.address.city'），两者的类型覆盖范围不匹配。

解决方案 #

1. 基础版：调整Props类型适配FieldPath<T> #

直接使用React Hook Form内置的FieldPath<T>约束name属性，同时保留泛型T关联表单数据结构：

import { FieldValues, Control, Controller, FieldPath } from "react-hook-form";
import { Stack, TextField } from "@mui/material";

interface GenericTextfieldProps<T extends FieldValues> {
  formLabel: string;
  // 用FieldPath<T>替代keyof T，兼容顶层和嵌套字段路径
  name: FieldPath<T>;
  control: Control<T>;
}

function GenericTextfield<T extends FieldValues>({
  formLabel,
  name,
  control,
}: GenericTextfieldProps<T>) {
  return (
    <Stack direction="column" spacing={0.5}>
      <Controller
        render={({ field }) => (
          <TextField
            {...field}
            id={name} // 用name作为id，避免全局重复id问题
            label={formLabel} // 传入formLabel作为输入框标签
            size="small"
            fullWidth
            sx={{ ml: 3 }}
            disabled
            variant="outlined"
          />
        )}
        name={name}
        control={control}
      />
    </Stack>
  );
}

2. 进阶版：更精确的泛型约束（可选） #

如果需要严格绑定字段名与对应值的类型，可以添加第二个泛型参数TName指定具体字段路径，还能支持默认值的类型校验：

import { FieldValues, Control, Controller, FieldPath, FieldPathValue } from "react-hook-form";
import { Stack, TextField } from "@mui/material";

interface GenericTextfieldProps<T extends FieldValues, TName extends FieldPath<T>> {
  formLabel: string;
  name: TName;
  control: Control<T>;
  // 用FieldPathValue自动推导对应字段的类型
  defaultValue?: FieldPathValue<T, TName>;
}

function GenericTextfield<T extends FieldValues, TName extends FieldPath<T>>({
  formLabel,
  name,
  control,
  defaultValue,
}: GenericTextfieldProps<T, TName>) {
  return (
    <Stack direction="column" spacing={0.5}>
      <Controller
        render={({ field }) => (
          <TextField
            {...field}
            id={name}
            label={formLabel}
            size="small"
            fullWidth
            sx={{ ml: 3 }}
            disabled
            variant="outlined"
          />
        )}
        name={name}
        control={control}
        defaultValue={defaultValue}
      />
    </Stack>
  );
}

使用示例 #

假设你的表单数据结构如下：

type FormData = {
  username: string;
  profile: {
    email: string;
    age: number;
  };
};

调用封装组件时，TypeScript会自动校验name的合法性：

import { useForm } from "react-hook-form";

function MyForm() {
  const { control } = useForm<FormData>();

  return (
    <div>
      <GenericTextfield<FormData> 
        formLabel="用户名" 
        name="username" 
        control={control} 
      />
      <GenericTextfield<FormData> 
        formLabel="邮箱" 
        name="profile.email" 
        control={control} 
      />
      {/* 无效字段会触发TypeScript报错 */}
      {/* <GenericTextfield<FormData> name="invalidField" control={control} /> */}
    </div>
  );
}

关键说明 #

• FieldPath<T>是React Hook Form专为表单字段路径设计的内置类型，完全匹配Controller的name参数要求，既支持顶层键也支持嵌套键。
• 无需再使用keyof T，因为FieldPath<T>已包含所有合法的字段路径（包括keyof T的所有顶层键）。
• 泛型T的存在能让TypeScript在组件使用阶段自动校验字段名合法性，确保表单数据类型一致。

内容的提问来源于stack exchange，提问作者Lys Ng