PropTypes联合类型TypeScript类型不兼容问题求更优解

问题背景 #

定义如下PropTypes时触发TypeScript类型错误：

position: PropTypes.oneOfType([
  PropTypes.oneOf([
    'auto',
    'above',
    'below',
    'auto left',
    'auto center',
    'auto right',
    'above left',
    'above center',
    'above right',
    'below left',
    'below center',
    'below right',
  ]),
  PropTypes.func,
])

错误信息 #

Type 'Requireable<NonNullable<string | ((...args: any[]) => any) | null | undefined>>' is not assignable to type 'Validator<"auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined>'.  
  Types of property '[nominalTypeHack]' are incompatible.
    Type '{ type: NonNullable<string | ((...args: any[]) => any) | null | undefined> | null | undefined; } | undefined' is not assignable to type '{ type: "auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined; } | undefined'.
      Type '{ type: NonNullable<string | ((...args: any[]) => any) | null | undefined> | null | undefined; }' is not assignable to type '{ type: "auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined; }'.
        Types of property 'type' are incompatible.
          Type 'NonNullable<string | ((...args: any[]) => any) | null | undefined> | null | undefined' is not assignable to type '"auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined'.
            Type 'string' is not assignable to type '"auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined'.ts(2322)

当前采用手动类型断言的方案，但需要重复编写冗长的联合类型，过于繁琐：

as PropTypes.Requireable<"auto" | "above" | "below" | "auto left" | "auto center" | "auto right" | "above left" | "above center" | "above right" | "below left" | "below center" | "below right" | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined>,

优雅解决方案 #

方案1：利用as const推导精确字面量类型+类型复用 #

核心思路是通过as const让TypeScript将字符串数组推断为只读字面量数组（而非宽泛的string[]），同时提前定义可复用的类型，避免重复编写：

// 1. 用as const让TS推导精确的字面量数组
const positionOptions = [
  'auto',
  'above',
  'below',
  'auto left',
  'auto center',
  'auto right',
  'above left',
  'above center',
  'above right',
  'below left',
  'below center',
  'below right',
] as const;

// 2. 从数组自动推导位置字符串的字面量类型
type PositionValue = typeof positionOptions[number];
// 3. 定义位置函数的类型
type PositionCallback = (self: Instance, customElement: HTMLElement | undefined) => void;
// 4. 合并成最终的Prop类型
type PositionProp = PositionValue | PositionCallback | null | undefined;

// 5. 定义PropTypes
position: PropTypes.oneOfType([
  PropTypes.oneOf(positionOptions),
  PropTypes.func as PropTypes.Requireable<PositionCallback>,
]) as PropTypes.Requireable<PositionProp>,

方案2：简化类型断言（轻量版） #

如果不想提前定义过多类型，至少可以优化函数部分的断言，同时用as const修复字符串部分的类型宽泛问题：

const positionOptions = [
  'auto',
  'above',
  'below',
  'auto left',
  'auto center',
  'auto right',
  'above left',
  'above center',
  'above right',
  'below left',
  'below center',
  'below right',
] as const;

position: PropTypes.oneOfType([
  PropTypes.oneOf(positionOptions),
  PropTypes.func as PropTypes.Requireable<(self: Instance, customElement: HTMLElement | undefined) => void>,
]) as PropTypes.Requireable<typeof positionOptions[number] | ((self: Instance, customElement: HTMLElement | undefined) => void) | null | undefined>,

错误原因解析 #

原代码中，PropTypes.oneOf([...])的字符串数组被TypeScript默认推断为string[]，导致oneOf返回的类型是Requireable<string>，无法匹配你期望的精确字面量联合类型。as const会将数组标记为只读的字面量集合，让TypeScript推导出每个元素的具体字面量值，从而对齐目标Prop类型。

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