TypeScript React表单构建器泛型困境：被迫使用unknown类型

问题背景 #

我用TypeScript开发React表单构建器，每个组件的value类型和onChange返回值类型都不一样，想通过泛型实现强类型校验，明确每个组件的输入输出类型。

底层表单字段组件接口 #

interface FormFieldProps<T> {
  value: T;
  onChange: (value: { [key: string]: T }) => void;
}

顶层表单构建器组件接口 #

interface FormBuilderProps<T> {
    fields: FormFieldProps<T>[];
    onChange: (value: { [key: string]: T }) => void;
    formData: { [key: string]: T };
}

当前困境 #

给顶层FormBuilder指定泛型时，只有unknown或any能适配所有组件（比如有的组件接受string、string[]、number等类型）。比如这么定义：

const FormBuilder = (props: FormBuilderProps<unknown>) => {...}

虽然用unknown消除了类型错误，但所有类型都变成unknown，会出现类型不安全的情况——比如把number传给期望string的组件。

另外，尝试给FormBuilderProps指定具体类型（比如string）时，TEXT组件正常，但SWITCH组件会报错boolean不能赋值给string类型。现在想问：是不是必须给T指定所有可能选项，然后在每个组件里用类型守卫？

补充：每个fields项会通过JavaScript的switch()根据componentType渲染对应组件，如果能通过枚举缩小T的类型会很有用。示例代码如下：

export const formBuilderData: FormBuilderProps<string> = {
  fields: [
    {
      index: 1,
      columnName: 'columnName',
      componentType: PureComponentType.TEXT,
      value: 'alphabet',
    },
    {
      index: 2,
      columnName: 'bestBear',
      componentType: PureComponentType.SWITCH,
      value: true,
  ],
  readOnly: false,
  formData: {},
};

解决方案 #

不用unknown或any，也不用手动写大量类型守卫，通过组件类型-值类型映射+条件类型就能实现强类型校验：

1. 绑定组件类型与值类型 #

先定义组件类型枚举，再做一个映射表，把每个组件类型和它对应的value类型绑定：

// 组件类型枚举
enum PureComponentType {
  TEXT = 'TEXT',
  SWITCH = 'SWITCH',
  SELECT = 'SELECT',
  NUMBER_INPUT = 'NUMBER_INPUT',
}

// 组件类型到值类型的映射
type ComponentValueMap = {
  [PureComponentType.TEXT]: string;
  [PureComponentType.SWITCH]: boolean;
  [PureComponentType.SELECT]: string[];
  [PureComponentType.NUMBER_INPUT]: number;
};

2. 重构FormFieldProps为条件类型 #

让FormFieldProps根据组件类型自动匹配value类型，不再用单一泛型T：

type FormFieldProps<K extends PureComponentType> = {
  index: number;
  columnName: string;
  componentType: K;
  value: ComponentValueMap[K];
  onChange: (value: { [key: string]: ComponentValueMap[K] }) => void;
};

3. 重构FormBuilderProps适配联合字段 #

顶层的FormBuilderProps改为接受字段数组的泛型，自动推导整个表单的formData类型：

// 自动推导表单数据结构：键是字段名，值是对应组件的value类型
type FormData<Fields extends FormFieldProps<PureComponentType>[]> = {
  [F in Fields[number] as F['columnName']]: F['value'];
};

interface FormBuilderProps<Fields extends FormFieldProps<PureComponentType>[]> {
  fields: Fields;
  onChange: (value: FormData<Fields>) => void;
  formData: FormData<Fields>;
  readOnly?: boolean;
}

4. 使用示例 #

现在定义表单数据时，TypeScript会自动校验每个字段的value类型是否匹配组件类型，formData和onChange的参数类型也会自动推导：

const formBuilderData: FormBuilderProps<[
  FormFieldProps<PureComponentType.TEXT>,
  FormFieldProps<PureComponentType.SWITCH>
]> = {
  fields: [
    {
      index: 1,
      columnName: 'columnName',
      componentType: PureComponentType.TEXT,
      value: 'alphabet',
      onChange: (val) => {},
    },
    {
      index: 2,
      columnName: 'bestBear',
      componentType: PureComponentType.SWITCH,
      value: true,
      onChange: (val) => {},
    },
  ],
  readOnly: false,
  formData: {
    columnName: 'initial text',
    bestBear: false,
  },
  onChange: (formData) => {
    // formData类型自动推导为 { columnName: string; bestBear: boolean }
    console.log(formData.columnName, formData.bestBear);
  },
};

5. 渲染时自动类型缩小 #

在switch渲染组件时，TypeScript会根据componentType自动缩小value的类型，不需要额外类型守卫：

const renderField = (field: FormFieldProps<PureComponentType>) => {
  switch (field.componentType) {
    case PureComponentType.TEXT:
      // field.value自动推导为string
      return <TextInput value={field.value} onChange={field.onChange} />;
    case PureComponentType.SWITCH:
      // field.value自动推导为boolean
      return <SwitchInput value={field.value} onChange={field.onChange} />;
    case PureComponentType.SELECT:
      // field.value自动推导为string[]
      return <SelectInput value={field.value} onChange={field.onChange} />;
    case PureComponentType.NUMBER_INPUT:
      // field.value自动推导为number
      return <NumberInput value={field.value} onChange={field.onChange} />;
    default:
      throw new Error(`Unknown component type: ${field.componentType}`);
  }
};

总结 #

• 无需用unknown或any，通过映射表和条件类型实现全链路强类型校验
• 表单数据类型自动推导，确保每个字段类型和组件匹配
• 渲染时利用TypeScript控制流分析自动缩小类型，不用手动写类型守卫

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