React组件中该联合类型Props为何解构时报错？

问题背景 #

我正在开发一个可同时作为容器或子项的Grid组件，通过container: boolean属性区分两种状态：当container为true时，组件拥有额外的布局属性。对应的类型定义如下：

interface ExtendedProps {
    cols?: Areas
    rows?: Areas
    gap?: Spacing
}

type GridProps = {
    container?: false;
    children: ReactNode;
};

type ContainerProps = Omit<GridProps, 'container'> & ExtendedProps & {
  container: true;
};

遇到的报错 #

在解构组件Props时，TypeScript抛出如下错误：

export default function Grid({
    container,
    children,
    gap, // Property 'gap' does not exist on type 'GridProps | ContainerProps'.
    cols, // Property 'cols' does not exist on type 'GridProps | ContainerProps'.
    rows, // Property 'rows' does not exist on type 'GridProps | ContainerProps'.
}: ContainerProps | GridProps) {
    // ...
}

疑惑点 #

直接定义ContainerProps | GridProps类型的对象时，类型检查却符合预期：

const testObject: ContainerProps | GridProps = {
    children: <div />,
    container: false,
    gap: 2 // 报错：类型不匹配
}

const anotherTestObject: ContainerProps | GridProps = {
    children: <div />,
    container: true,
    gap: 2
}

报错原因 #

这是因为联合类型的属性访问规则：当访问联合类型的属性时，TypeScript仅允许访问所有联合成员共有的属性。

在GridProps | ContainerProps联合类型中，GridProps并没有gap、cols、rows这些属性，所以直接解构访问这些属性时，TypeScript无法确定当前Props属于哪一个类型，因此会报错阻止访问仅存在于部分类型的属性。

而直接定义对象时，TypeScript会通过字面量值自动收窄类型：当你明确赋值container: true时，对象类型会被收窄为ContainerProps，此时允许访问额外属性；赋值container: false时，类型收窄为GridProps，添加额外属性就会触发报错，这完全符合预期。

解决方法 #

可以在组件内部通过类型守卫收窄类型，确保安全访问属性：

export default function Grid(props: ContainerProps | GridProps) {
    const { container, children } = props;
    if (container) {
        // 此处props被自动收窄为ContainerProps，可安全访问gap、cols、rows
        const { gap, cols, rows } = props;
        // 容器逻辑处理
    } else {
        // 此处props为GridProps，无额外属性
        // 子项逻辑处理
    }
}

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