Vue+TypeScript条件式Props实现遇问题，求正确方案

需求规则 #

• title为必填项
• 若isRepeatableParent或isRepeatableChild设为true（二者为可选布尔类型），则repeatableControls为必填项
• 若isRepeatableChild设为true，则subtitle为必填项

现有实现代码 #

type BaseProps = {
    title: string;
};

type RepeatableParentProps = BaseProps & {
    isRepeatableParent: true;
    repeatableControls: IRepeatableControls<IRepeatableBlock>;
    isRepeatableChild?: never;
    subtitle?: never;
};

type RepeatableChildProps = BaseProps & {
    isRepeatableChild: true;
    repeatableControls: IRepeatableControls<IRepeatableBlock>;
    subtitle: string;
    isRepeatableParent?: never;
};

type OtherProps = BaseProps & {
    isRepeatableParent?: false;
    isRepeatableChild?: false;
    repeatableControls?: never;
    subtitle?: never;
};

type Props = RepeatableParentProps | RepeatableChildProps | OtherProps;

const props = defineProps<Props>();

遇到的问题 #

• 设置is-repeatable-parent属性时，添加subtitle不会触发TypeScript错误
• 使用PHPStorm作为IDE时，有时会丢失除title外的所有Props提示
• 尝试用类型收窄的方式解决，但没有效果

问题原因与解决方案 #

1. 为什么subtitle不会触发错误？ #

你的类型定义里，RepeatableParentProps用了subtitle?: never，但在Vue的Props解析逻辑中，可选的never类型并不会完全禁止传入该属性——因为never?等价于undefined | never，最终会被TypeScript简化为undefined，所以不会触发报错。要彻底禁止传入，应该把subtitle设为必填的never，而非可选。

2. IDE提示丢失的问题 #

联合类型在Vue的Script Setup中，IDE对defineProps的类型推导支持有限，尤其是复杂联合类型。可以通过优化联合类型定义，或者改用对象式Props定义（结合PropType）来提升IDE的识别度。

修正后的代码实现 #

方案一：优化联合类型定义

type BaseProps = {
    title: string;
};

// 明确禁止不需要的属性，用必填never而非可选never
type RepeatableParentProps = BaseProps & {
    isRepeatableParent: true;
    repeatableControls: IRepeatableControls<IRepeatableBlock>;
    isRepeatableChild?: never;
    subtitle: never; // 改为必填never，彻底禁止传入
};

type RepeatableChildProps = BaseProps & {
    isRepeatableChild: true;
    repeatableControls: IRepeatableControls<IRepeatableBlock>;
    subtitle: string;
    isRepeatableParent?: never;
};

type OtherProps = BaseProps & {
    isRepeatableParent?: false;
    isRepeatableChild?: false;
    repeatableControls?: never;
    subtitle?: never;
};

type Props = RepeatableParentProps | RepeatableChildProps | OtherProps;

const props = defineProps<Props>();

方案二：改用对象式Props定义（更友好的IDE支持）

如果联合类型的IDE提示问题依然存在，推荐用Vue官方的对象式定义结合PropType，兼容性更好：

import type { PropType } from 'vue';

const props = defineProps({
    title: {
        type: String,
        required: true,
    },
    isRepeatableParent: {
        type: Boolean,
        default: false,
    },
    isRepeatableChild: {
        type: Boolean,
        default: false,
    },
    repeatableControls: {
        type: Object as PropType<IRepeatableControls<IRepeatableBlock>>,
        required: false,
        // 运行时校验补充编译时规则
        validator: (value: unknown, props: any) => {
            if (props.isRepeatableParent || props.isRepeatableChild) {
                return value !== undefined;
            }
            return true;
        },
    },
    subtitle: {
        type: String,
        required: false,
        validator: (value: unknown, props: any) => {
            if (props.isRepeatableChild) {
                return typeof value === 'string' && value.trim() !== '';
            }
            return true;
        },
    },
});

// 组件内使用时通过类型守卫收窄类型，获得准确提示
function getCurrentProps() {
    if (props.isRepeatableParent) {
        return props as typeof props & { 
            isRepeatableParent: true; 
            repeatableControls: IRepeatableControls<IRepeatableBlock> 
        };
    } else if (props.isRepeatableChild) {
        return props as typeof props & { 
            isRepeatableChild: true; 
            repeatableControls: IRepeatableControls<IRepeatableBlock>;
            subtitle: string 
        };
    } else {
        return props as typeof props;
    }
}

const currentProps = getCurrentProps();

额外说明 #

• 对于TypeScript的联合类型，要严格禁止某个属性，必须使用property: never（必填），而不是property?: never，因为可选的never会被TypeScript忽略。
• PHPStorm对Vue的Script Setup联合类型Props的支持确实有局限性，改用对象式定义配合类型断言/守卫，能有效提升提示准确性。
• 运行时的validator可以补充TypeScript编译时的校验，避免在非TS环境下传入不符合规则的属性。

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