TypeScript中如何允许任意Props同时实现判别式联合约束？

问题背景 #

开发React组件库时需要实现两个核心需求：

1. 组件支持自定义Props（如data-*、aria-*这类任意属性）
2. 强制组件必须传入children或text中的一个，且不能同时传入

最初通过在Props接口中添加[x: string]: unknown实现自定义Props支持，但将该索引签名加入公共基础接口后，原本生效的children/text互斥约束失效——同时传入两个属性时TypeScript不再报错。

问题原因 #

当接口包含[x: string]: unknown索引签名时，TypeScript会判定所有字符串键的属性都是合法的，包括children和text。这会直接覆盖联合类型中通过never实现的互斥约束，因为TypeScript会将冲突属性解释为符合索引签名的任意属性，而非违反联合类型定义的错误。

解决方案 #

方案1：将索引签名添加到子接口而非公共接口 #

把自定义Props的索引签名分别加到两个互斥的子接口中，公共基础接口仅保留组件的特定Props，既保留联合类型的互斥约束，又支持自定义属性：

import type { ReactNode } from 'react';

// 公共基础Props：仅包含组件特定属性，无索引签名
interface LinkPropsCommon {
  color?: string;
  icon?: ReactNode;
  // 其他组件特定属性...
}

// 仅允许传入children的子类型，添加自定义Props支持
interface LinkPropsChildren extends LinkPropsCommon {
  children: ReactNode;
  text?: never; // 禁止同时传入text
  [x: string]: unknown; // 支持任意自定义Props
}

// 仅允许传入text的子类型，添加自定义Props支持
interface LinkPropsText extends LinkPropsCommon {
  children?: never; // 禁止同时传入children
  text: string;
  [x: string]: unknown; // 支持任意自定义Props
}

// 最终联合类型Props
type LinkProps = LinkPropsChildren | LinkPropsText;

验证效果

• 合法用法：

  // 仅传children，支持自定义属性
  <Link color="blue" data-id="123">示例链接</Link>
  // 仅传text，支持自定义属性
  <Link text="示例链接" aria-label="跳转链接" />
  

• 非法用法（TypeScript会报错）：

  // 同时传入children和text，违反互斥约束
  <Link text="示例链接">示例链接</Link>
  

方案2：用交叉类型组合联合约束与自定义Props #

如果希望保持公共接口结构，也可以将基础联合类型与带有索引签名的类型交叉：

import type { ReactNode } from 'react';

interface LinkPropsCommon {
  color?: string;
  icon?: ReactNode;
}

interface LinkPropsChildren extends LinkPropsCommon {
  children: ReactNode;
  text?: never;
}

interface LinkPropsText extends LinkPropsCommon {
  children?: never;
  text: string;
}

// 先定义互斥的联合类型，再交叉自定义Props支持
type LinkProps = (LinkPropsChildren | LinkPropsText) & { [x: string]: unknown };

这种方式同样生效，当同时传入children和text时，TypeScript会将这两个属性的类型解析为ReactNode & never（即never），从而触发类型错误。

补充说明 #

如果组件是基于原生HTML元素封装（比如<a>标签），可以用React.HTMLAttributes<HTMLElement>替代[x: string]: unknown，既能支持所有原生HTML属性，又能获得更准确的类型提示：

// 替换索引签名为HTMLAttributes
interface LinkPropsChildren extends LinkPropsCommon, React.HTMLAttributes<HTMLElement> {
  children: ReactNode;
  text?: never;
}

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