TypeScript字符串联合类型下属性'type'不兼容问题排查

组件代码 #

const GridCell = <T extends keyof FormValue>(props: GridCellProps<T>) => {
  // ...组件逻辑
}

const GridRow = <T extends keyof FormValue>(props: GridRowProps<T>) => {
  // ...组件逻辑
  <GridCell
    type={props.type} // <-- 此处出现类型错误
    fractionDigits={props.fractionDigits}
    // 其他props
  />
  // ...组件逻辑
}

类型定义 #

export type GridRowFieldType<T extends keyof FormValue> = {
  isDetail: boolean;
  highlighted: boolean;
  label: string;
  fieldName: T;
} & (
  | { type: 'date' | 'duration'; fractionDigits?: never }
  | { type: 'number'; fractionDigits: number }
);

export type GridRowProps<T extends keyof FormValue> = {
  showDetails: boolean;
  values: FormValue[T];
} & GridRowFieldType<T>;


export type GridCellProps<T extends keyof FormValue> = {
  label: string;
  fieldName: T;
  index: number;
} & (
  | {
      type: 'date';
      value: DateFieldValueType | undefined;
      fractionDigits?: never;
    }
  | {
      type: 'duration';
      value: DurationFieldValueType | undefined;
      fractionDigits?: never;
    }
  | { type: 'number'; value: number | undefined; fractionDigits: number }
);

报错信息 #

Types of property 'type' are incompatible.
      Type '"number" | "date" | "duration"' is not assignable to type '"number"'.
        Type '"date"' is not assignable to type '"number"'.ts(2322)

问题背景 #

尽管type的实际取值范围是"number" | "date" | "duration"，但TypeScript仍抛出类型不兼容错误。若将GridCellProps的联合类型简化为type: 'date' | 'duration' | 'number';，错误会消失，但无法通过type的值约束value属性的类型，不符合需求。

解决方案 #

方案1：泛型细化类型关联（推荐，保证类型安全） #

问题根源在于TypeScript无法自动匹配GridRowProps和GridCellProps的联合类型分支。可以通过新增泛型参数，将type的具体值与对应属性类型绑定：

首先定义类型映射表，统一管理type与对应属性的关系：

// 定义type和对应属性的映射
type CellTypeConfig = {
  date: { value: DateFieldValueType | undefined; fractionDigits?: never };
  duration: { value: DurationFieldValueType | undefined; fractionDigits?: never };
  number: { value: number | undefined; fractionDigits: number };
};

重构GridCellProps，通过泛型参数关联type的具体值：

export type GridCellProps<T extends keyof FormValue, K extends keyof CellTypeConfig> = {
  label: string;
  fieldName: T;
  index: number;
  type: K;
} & CellTypeConfig[K];

修改组件定义，让TypeScript能精确推断类型分支：

const GridCell = <T extends keyof FormValue, K extends keyof CellTypeConfig>(props: GridCellProps<T, K>) => {
  // ...组件逻辑
};

const GridRow = <T extends keyof FormValue, K extends keyof CellTypeConfig>(
  props: GridRowProps<T> & { type: K }
) => {
  // ...组件逻辑
  <GridCell<T, K>
    type={props.type}
    fractionDigits={props.fractionDigits}
    value={props.values}
    label={props.label}
    fieldName={props.fieldName}
    index={0} // 替换为实际index值
  />
};

方案2：类型断言（快速解决，需谨慎使用） #

如果不想调整泛型结构，可以用类型断言强制告诉TypeScript当前props符合GridCellProps的约束：

<GridCell
  {...props as unknown as GridCellProps<T>}
  index={0} // 补充GridCell必需的index属性
/>

注意：这种方式跳过了TypeScript的类型检查，需确保实际传递的props完全符合GridCellProps的结构，避免运行时错误。

原因分析 #

GridRowFieldType将date和duration合并为一个联合分支，而GridCellProps是三个独立的联合分支。TypeScript无法自动将前者的type联合类型（"number" | "date" | "duration"）与后者的分支做精确匹配，因此认为type可能与GridCellProps的某个分支不兼容，抛出错误。

内容的提问来源于stack exchange，提问作者Renaud is Not Bill Gates