React+TypeScript：能否重载泛型数量不同的函数？

我正在用TypeScript编写React函数组件，想做一个支持提交前格式化数据的Form组件——可选传入format函数和FormattedValue泛型，但必须满足「要么同时设置FormattedValue泛型和format参数，要么都不设置」的规则，防止提交类型错误的数据。尝试用函数重载实现这个逻辑时，遇到了报错：This overload signature is not compatible with its implementation signature.(2394)，而且不想把普通表单和带格式化的表单拆成两个独立组件。

我的尝试代码如下：

import { Form } from "../components/Form"

type FormProps<Value> = {
    submit: (data: Value) => void;
}

type FormattedFormProps<Value, FormattedValue> = {
    submit: (data: FormattedValue) => void;
    format: (value: Value) => FormattedValue
}

function GenericForm<V>({ submit }: FormProps<V>): React.ReactNode;
function GenericForm<V, F>({ submit, format }: FormattedFormProps<V, F>) {
  return (
    <Form 
     //...
    onSubmit={(value) => {
        submit(format ? format(value) : value)
    }}
    >
     // ...
    </Form>
  )
}

export default GenericForm

问题根源 #

函数重载的所有签名必须和底层实现的签名兼容。你的实现签名里包含了format参数，但第一个重载签名完全没有这个参数，TypeScript会判定实现逻辑可能接收到无format的props，但代码里直接使用了format，导致类型不匹配。

修复方案 #

不用拆分成两个组件，通过联合类型+类型收窄或者条件泛型约束就能实现需求：

方案1：联合类型统一props定义

把两种场景的props合并成联合类型，用format的存在性区分，再通过类型收窄处理逻辑：

import { Form } from "../components/Form";
import type React from "react";

// 合并普通表单和带格式化表单的props
type GenericFormProps<V, F = V> = 
  | { submit: (data: V) => void; format?: undefined }
  | { submit: (data: F) => void; format: (value: V) => F };

function GenericForm<V, F = V>(props: GenericFormProps<V, F>): React.ReactNode {
  const { submit, format } = props;
  
  return (
    <Form
      onSubmit={(value: V) => {
        // 类型收窄：有format就格式化，否则直接传原始值
        submit(format ? format(value) : (value as unknown as F));
      }}
    >
      {/* 表单内容 */}
    </Form>
  );
}

export default GenericForm;

方案2：条件泛型强制约束关系

通过泛型条件判断，强制要求传入format时必须指定FormattedValue泛型，否则泛型默认和原始值类型一致：

import { Form } from "../components/Form";
import type React from "react";

type GenericFormProps<V, F> = {
  submit: (data: F) => void;
  // 当F和V类型相同时，禁止传入format；否则必须传入符合类型的format
  format?: F extends V ? never : (value: V) => F;
};

function GenericForm<V, F = V>(props: GenericFormProps<V, F>): React.ReactNode {
  const { submit, format } = props;
  
  return (
    <Form
      onSubmit={(value: V) => {
        submit(format ? format(value) : (value as F));
      }}
    >
      {/* 表单内容 */}
    </Form>
  );
}

// 使用示例：
// 普通表单：无需format和额外泛型
<GenericForm submit={(data: { name: string }) => console.log(data)} />;

// 带格式化的表单：必须指定泛型并传入format
<GenericForm<{ name: string }, string>
  submit={(data) => console.log(data)}
  format={(value) => value.name}
/>;

效果说明 #

• 不传入format时，泛型默认和表单原始值类型一致，submit接收原始数据类型
• 传入format时，TypeScript会强制校验format的返回类型和submit的参数类型匹配，同时必须显式指定泛型（或让TS自动推导），从根源避免类型错误

内容的提问来源于stack exchange，提问作者Navier Stokes