如何用react-hook-form创建基于主表单字段子集的类型安全可复用子表单

问题描述 #

需求是抽离一个仅依赖大型表单字段子集的可复用子表单组件，相关代码及遇到的问题如下：

类型定义 #

// 子表单所需的字段接口
interface JobData {
  position: string;
  salary: number;
}

// 主表单完整数据接口，继承子表单字段
interface Data extends JobData {
  name: string;
  birthDate: string;
}

初始子表单实现 #

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

interface JobFormProps {
  control: Control<JobData>;
}

const JobForm = ({ control }: JobFormProps) => {
  return (
    <div>
      <ControlledInput control={control} controlName="position" />
      <ControlledInput control={control} controlName="salary" />
    </div>
  );
};

主表单调用子表单 #

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

const MainForm = () => {
  const { control } = useForm<Data>({
    defaultValues: {
      name: "John",
      birthDate: "1980-01-01",
      position: "Developer",
      salary: 100000
    }
  });

  return (
    <div>
      <ControlledInput control={control} controlName="name" />
      <ControlledInput control={control} controlName="birthDate" />
      <JobForm control={control} /> {/* 此处触发类型错误 */}
    </div>
  );
};

类型错误信息 #

Type 'Control<Data, any>' is not assignable to type 'Control<JobData>'.
  Types of property '_reset' are incompatible.
    Type 'UseFormReset<Data>' is not assignable to type 'UseFormReset<JobData>'.

尝试过的方案及问题 #

• 将JobFormProps设为泛型，但字段名称无法被TypeScript自动识别；
• 强制类型转换control，仍出现相同类型错误；
• 将Data所有字段设为可选，虽解决类型问题但不符合业务需求（部分字段应为必填）。

补充：曾尝试泛型方案，但需强制转换字段名，无法保证完全类型安全：

import { Control, Path } from "react-hook-form";

interface JobFormProps<T extends JobData> {
  control: Control<T>;
}

const JobForm = <T extends JobData>({ control }: JobFormProps<T>) => {
  return (
    <div>
      <ControlledInput control={control} controlName={"position" as Path<T>} />
      <ControlledInput control={control} controlName={"salary" as Path<T>} />
    </div>
  );
};

类型安全的解决方案 #

核心思路是让子表单的Control类型兼容父表单的Control，同时保证字段名称的类型推导完全可靠，无需强制转换。

方案1：泛型约束+自动路径推导 #

通过泛型约束父类型必须包含JobData的所有字段，借助React Hook Form的Path类型自动推导合法字段名：

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

type JobFields = JobData;

// 约束泛型T必须包含JobFields的所有字段
interface JobFormProps<T extends JobFields> {
  control: Control<T>;
}

const JobForm = <T extends JobFields>({ control }: JobFormProps<T>) => {
  return (
    <div>
      {/* 字段名自动匹配类型，无需强制转换 */}
      <ControlledInput control={control} controlName="position" />
      <ControlledInput control={control} controlName="salary" />
    </div>
  );
};

方案2：严格限制Control的可访问字段 #

如果需要明确子表单仅能操作JobData范围内的字段，可以通过Pick和类型拼接，创建仅包含目标字段能力的Control类型：

import { Control, Path } from "react-hook-form";

interface JobFormProps<T extends JobData> {
  // 仅保留T中属于JobData的字段对应的Control方法
  control: Omit<Control<T>, '_reset' | 'setValue'> & {
    setValue: (name: Path<Pick<T, keyof JobData>>, value: any, options?: any) => void;
    _reset: (values?: Partial<Pick<T, keyof JobData>>) => void;
  };
}

const JobForm = <T extends JobData>({ control }: JobFormProps<T>) => {
  return (
    <div>
      <ControlledInput control={control} controlName="position" />
      <ControlledInput control={control} controlName="salary" />
    </div>
  );
};

方案3：使用FormContext（复杂嵌套表单首选） #

对于多层嵌套的表单场景，可借助React Hook Form的FormProvider和useFormContext，子表单无需传递control，直接从上下文获取类型兼容的表单方法：

// 主表单
import { FormProvider, useForm } from "react-hook-form";

const MainForm = () => {
  const methods = useForm<Data>({
    defaultValues: {
      name: "John",
      birthDate: "1980-01-01",
      position: "Developer",
      salary: 100000
    }
  });

  return (
    <FormProvider {...methods}>
      <div>
        <ControlledInput control={methods.control} controlName="name" />
        <ControlledInput control={methods.control} controlName="birthDate" />
        <JobForm /> {/* 无需传递control */}
      </div>
    </FormProvider>
  );
};

// 子表单
import { useFormContext } from "react-hook-form";

// 若需通用化，可改为泛型版本：const JobForm = <T extends JobData>() => { ... }
const JobForm = () => {
  const { control } = useFormContext<Data>();
  return (
    <div>
      <ControlledInput control={control} controlName="position" />
      <ControlledInput control={control} controlName="salary" />
    </div>
  );
};

错误根源 #

Control<Data>与Control<JobData>属于逆变类型，父类型的Control无法直接赋值给子类型的Control——因为_reset、setValue等方法的参数类型范围不同（父类型允许操作更多字段）。通过泛型约束或限制可访问字段，可实现类型兼容，同时保证操作的类型安全性。

内容的提问来源于stack exchange，提问作者Krisztian Zsobrak