Vue3+TypeScript如何实现组件Props二选一（color/imagePath）约束

我有一个用于显示文本以及图片或彩色圆形的组件，效果如下：

当前组件的Props定义如下：

<script lang="ts" setup>
    // Props
    interface Props {
        title: string 
        imagePath?: string   // 图片资源的字符串路径
        color?: `#${string}` // 以#开头的字符串，例如#16A2B0
    }
    const props = defineProps<Props>()

[...]

</script>

传入color属性使用组件的示例：

<MyComponent color="#DEDEDE"/>

传入imagePath属性使用组件的示例：

<MyComponent image-path="src/assets/image.png" />

目前我将color和imagePath都设为可选属性，因为不存在同时需要两者的场景，但这也导致用户可能两者都不传，这是不允许的。

请问在Vue3 Composition API搭配TypeScript的情况下，能否指定该组件必须传入color或imagePath中的一个，不能同时传入两者，也不能都不传？

当然可以！用TypeScript的联合类型就能搞定这个互斥且必传其一的需求，再配合Vue的运行时验证双保险。

1. 用联合类型约束Props #

把原来的Props拆成两个互斥的接口，再用联合类型组合：

<script lang="ts" setup>
// 基础必传属性
interface BaseProps {
  title: string
}

// 仅传图片的场景：必须有imagePath，禁止传color
interface WithImageProps extends BaseProps {
  imagePath: string
  color?: never // 明确标记color不能传
}

// 仅传颜色的场景：必须有color，禁止传imagePath
interface WithColorProps extends BaseProps {
  color: `#${string}`
  imagePath?: never // 明确标记imagePath不能传
}

// 最终Props类型：二选一，不能同时传也不能都不传
type Props = WithImageProps | WithColorProps

const props = defineProps<Props>()
</script>

这样TypeScript编译阶段就会直接报错拦截：

• 同时传color和imagePath
• 两个都不传
• 格式不符合的颜色值（比如不带#的）

2. 加个运行时验证（可选但靠谱） #

TypeScript只在编译阶段生效，要是碰到非TS项目或者运行时的错误传入，加个运行时验证更稳妥：

<script lang="ts" setup>
// 上面的类型定义保留...

const props = defineProps<Props>({
  title: {
    type: String,
    required: true
  },
  imagePath: {
    type: String,
    validator: () => {
      // 传了imagePath就不能有color
      return !('color' in props)
    }
  },
  color: {
    type: String,
    validator: (val: string) => {
      // 先验证颜色格式是#开头的十六进制
      const hexReg = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/
      // 传了color就不能有imagePath
      return hexReg.test(val) && !('imagePath' in props)
    }
  }
})
</script>

3. 正确/错误用法示例 #

✅ 正确用法：

<MyComponent title="图片卡片" image-path="src/assets/avatar.png" />
<MyComponent title="彩色卡片" color="#16A2B0" />

❌ 错误用法（会被拦截）：

<!-- 同时传两个属性 -->
<MyComponent title="错误" image-path="src/assets/avatar.png" color="#DEDEDE" />
<!-- 两个都不传 -->
<MyComponent title="错误" />
<!-- 颜色格式不对 -->
<MyComponent title="错误" color="16A2B0" />

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