说实话，当你习惯了 React 那种“一切皆 Props”的直觉，再回头看 Vue 3 的接口设计，往往会有一种“为什么这么麻烦”的错觉。特别是当你试图构建一个跨框架或者在 TypeScript 加持下追求极致类型体验的组件库时，这种冲突会更加明显。
今天我想和你聊聊这个话题，不是那种教科书式的定义罗列，而是基于真实项目中踩过的坑，聊聊怎么让你的组件既好用，又不容易报错。
一、先别急着写 Props，先想清楚“边界”
很多开发者（包括以前的我）在写组件库时，第一步往往是把需要的数据列出来：title、count、onSubmit……然后直接定义成 Props。
但 Vue 3 和 React 最大的不同在于，Vue 是响应式的，而 React 是不可变的。这意味着 Vue 的组件设计需要更多地考虑“数据的流向”和“变化的时机”。
常见的错误示范
// ❌ 这种设计在 React 中很常见，但在 Vue 3 中会有坑
interface MyButtonProps {
loading: boolean;
onClick: () => void;
disabled: boolean;
}
看起来没问题，对吧？但问题在于：
loading和disabled往往是联动的，但这里没有约束。onClick是一个裸函数，没有考虑事件对象的类型。- 没有默认值，开发者每次都要传，或者自己处理 undefined。
更好的起点：定义明确的“契约”
在 Vue 3 中，我们应该先思考：这个组件的核心职责是什么？
比如一个 BaseButton，它的核心职责是“提供一个可点击的按钮，可以显示加载状态”。那么接口应该这样设计：
// ✅ 更清晰的职责分离
export interface BaseButtonProps {
/** 按钮文字，必填 */
text: string;
/** 是否加载中，默认 false */
loading?: boolean;
/** 是否禁用，默认 false */
disabled?: boolean;
/** 点击事件，自动排除重复触发 */
onClick?: (event: MouseEvent) => void;
}
看，这里的改进点：
- 每个属性都有注释，明确职责
- 可选属性用
?标记，但类型依然严格 onClick明确是MouseEvent，而不是裸() => void
二、类型安全 vs 易用性：那个永恒的矛盾
这是组件库设计中最核心的冲突。
场景一：事件处理器的类型推导
在 React 中，onClick 通常是 () => void 或者 React.MouseEventHandler。但在 Vue 3 中，如果你直接写：
// ❌ 太宽松了，开发者可能传任何类型的函数
onClick?: () => void;
开发者可能会这么用：
<BaseButton text="提交" @click="handleSubmit" />
但如果 handleSubmit 需要参数呢？或者需要访问事件对象呢？这时候就会出问题。
解决方案：使用泛型 + 事件类型
// ✅ 使用泛型，让类型更精确
export interface BaseButtonProps<T extends Event = MouseEvent> {
text: string;
loading?: boolean;
disabled?: boolean;
onClick?: (event: T) => void;
}
这样，当开发者传入一个需要参数的函数时，TypeScript 会直接报错：
// ❌ 类型错误！TypeScript 会提示
<BaseButton text="提交" @click="(e) => console.log(e)" />
Argument of type '(e: any) => void' is not assignable to parameter of type '(event: MouseEvent) => void'.
但等等，这样会不会太严格了？开发者可能只是想传一个无参函数。
平衡点：使用 Parameters 和 ReturnType 工具类型
// ✅ 更优雅的解法
type ClickEvent = MouseEvent;
type ClickHandler = (event: ClickEvent) => void;
export interface BaseButtonProps {
text: string;
loading?: boolean;
disabled?: boolean;
onClick?: ClickHandler;
}
这样既保持了类型安全，又不会因为过于复杂而吓跑开发者。
三、Vue 3 特有的坑：响应式 Props 的陷阱
这是从 React 转到 Vue 3 最容易踩的坑。
坑点：直接修改 Props
在 React 中，Props 是不可变的，你根本不能修改它们。但在 Vue 3 中，Props 是响应式的，你可以修改它们——但这绝对是个坏主意。
// ❌ 绝对不要这样做
defineProps<{
count: number;
}>();
// 在组件内部修改 count
count.value++; // 这会导致不可预测的行为
正确的做法：使用 computed 或 watch
// ✅ 正确的方式
const props = defineProps<{
count: number;
}>();
// 如果需要修改，使用内部状态
const internalCount = ref(props.count);
watch(() => props.count, (newVal) => {
internalCount.value = newVal;
});
或者，如果这个值确实需要被修改，那就不要作为 Props 传入，而是作为 modelValue 使用 v-model。
四、v-model 的现代化用法：一次绑定多个属性
React 没有 v-model，但 Vue 3 的 v-model 非常强大。很多开发者只用了 v-model 绑定一个值，但其实它可以绑定多个属性。
传统用法：单值绑定
// 组件定义
const props = defineProps<{
modelValue: string;
}>();
const emit = defineEmits<{
(e: 'update:modelValue', value: string): void;
}>();
// 使用
<BaseInput v-model="searchText" />
高级用法：多属性绑定
// 组件定义
const props = defineProps<{
modelValue: string;
active: boolean;
}>();
const emit = defineEmits<{
(e: 'update:modelValue', value: string): void;
(e: 'update:active', value: boolean): void;
}>();
// 使用
<BaseInput
v-model="searchText"
v-model:active="isActive"
/>
这样可以让组件更灵活，同时也保持了类型的清晰。
五、插槽（Slots）的类型安全：被忽视的宝藏
React 有 children 和 props.children，但 Vue 3 的插槽可以做得更类型安全。
问题：插槽内容没有类型检查
// ❌ 插槽内容可以是任何东西
<template>
<div>
<slot />
</div>
</template>
解决方案：具名插槽 + 类型约束
// ✅ 使用具名插槽，并为插槽内容定义类型
const props = defineProps<{
title: string;
}>();
// 插槽类型定义
type DefaultSlot = {
text: string;
count: number;
};
const slots = defineSlots<{
default(): VNode;
header(props: DefaultSlot): VNode;
}>();
// 使用
<BaseCard>
<template #header="{ text, count }">
<h1>{{ text }}</h1>
<span>{{ count }} items</span>
</template>
</BaseCard>
这样，当开发者使用 header 插槽时，TypeScript 会提示可用的属性。
六、从 React 迁移时的思维转换
1. 不要试图把 React 的模式照搬到 Vue
React 的 useState + useEffect 模式在 Vue 中对应的是 ref/reactive + watch/computed。但 Vue 的响应式系统更强大，你可以少写很多代码。
2. 事件命名：camelCase vs kebab-case
在 React 中，事件是 onClick、onChange。在 Vue 3 中，你可以用 onClick（在 script setup 中），但模板中通常用 @click。
保持一致性很重要。如果你的组件库同时支持两种用法，要明确文档说明。
3. 条件渲染：v-if vs &&
React 常用 condition && <Component />，但 Vue 中更推荐使用 v-if，因为它有更好的性能优化。
七、实际案例：一个完整的表单组件设计
让我们看一个完整的例子，把上面的原则都应用进去。
// components/FormInput.vue
<script setup lang="ts">
import { computed, ref, watch } from 'vue';
// 1. 定义 Props，每个属性都有明确的类型和注释
interface FormInputProps {
/** 输入框的标签文本 */
label: string;
/** 绑定的值，用于 v-model */
modelValue: string;
/** 占位符文本 */
placeholder?: string;
/** 是否必填 */
required?: boolean;
/** 校验规则 */
validator?: (value: string) => string | null;
/** 自定义错误信息 */
errorMessage?: string;
}
const props = withDefaults(defineProps<FormInputProps>(), {
placeholder: '',
required: false,
validator: null,
errorMessage: '',
});
// 2. 定义 Emits，使用元组语法，类型更清晰
const emit = defineEmits<{
(e: 'update:modelValue', value: string): void;
(e: 'blur', value: string): void;
(e: 'change', value: string): void;
}>();
// 3. 内部状态管理
const inputRef = ref<HTMLInputElement | null>(null);
const currentError = ref<string | null>(null);
// 4. 计算属性：根据校验规则动态生成错误信息
const displayError = computed(() => {
if (props.errorMessage) {
return props.errorMessage;
}
if (props.validator) {
return props.validator(props.modelValue);
}
return null;
});
// 5. 监听输入变化
function handleChange(event: Event) {
const target = event.target as HTMLInputElement;
const value = target.value;
emit('update:modelValue', value);
emit('change', value);
// 实时校验
if (props.validator) {
currentError.value = props.validator(value);
}
}
// 6. 监听失焦
function handleBlur(event: FocusEvent) {
emit('blur', props.modelValue);
}
</script>
<template>
<div class="form-input">
<label class="form-label">
{{ label }}
<span v-if="required" class="required">*</span>
</label>
<input
ref="inputRef"
:value="modelValue"
:placeholder="placeholder"
:class="{ 'input-error': displayError }"
@input="handleChange"
@blur="handleBlur"
/>
<span v-if="displayError" class="error-message">
{{ displayError }}
</span>
</div>
</template>
<style scoped>
.form-input {
display: flex;
flex-direction: column;
gap: 4px;
}
.form-label {
font-weight: 500;
}
.required {
color: red;
}
.input-error {
border-color: red;
}
.error-message {
color: red;
font-size: 12px;
}
</style>
这个设计的优点：
- 类型安全：所有 Props 和 Emits 都有明确的类型。
- 易用性：提供了默认值，可选属性都有合理的默认行为。
- 灵活性：支持自定义校验规则，也支持直接传入错误信息。
- 响应式：使用
computed动态生成错误信息，避免重复计算。 - 可扩展：通过
emit暴露了blur和change事件，方便上层组件监听。
八、测试你的组件库接口
写完后，一定要写测试用例，特别是类型测试。
// tests/FormInput.test.ts
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import FormInput from '../components/FormInput.vue';
describe('FormInput', () => {
it('should accept valid props', () => {
// 这个测试主要验证类型是否正确
const wrapper = mount(FormInput, {
props: {
label: '用户名',
modelValue: 'test',
required: true,
},
});
expect(wrapper.props('label')).toBe('用户名');
});
it('should emit update event on input', async () => {
const wrapper = mount(FormInput, {
props: {
label: '用户名',
modelValue: '',
},
});
await wrapper.find('input').setValue('new value');
expect(wrapper.emitted('update:modelValue')).toHaveLength(1);
expect(wrapper.emitted('update:modelValue')![0]).toEqual(['new value']);
});
it('should show error when validator fails', () => {
const wrapper = mount(FormInput, {
props: {
label: '邮箱',
modelValue: 'invalid-email',
validator: (value) => {
return value.includes('@') ? null : '请输入有效的邮箱地址';
},
},
});
expect(wrapper.text()).toContain('请输入有效的邮箱地址');
});
});
九、最后的建议：文档是最好的沟通工具
无论你设计得多好的接口，如果开发者看不懂，那就是失败的。
- JSDoc 注释：每个 Props 都要有清晰的注释。
- 示例代码：提供多个使用场景的示例。
- 类型导出：把 Props、Emits、Slots 的类型都导出，方便开发者使用。
// 导出类型，方便外部使用
export type FormInputProps = FormInputProps;
export type FormInputEmits = typeof emit;
结语
从 React 到 Vue 3，组件库的接口设计确实需要一些思维转换。但一旦你掌握了这些原则，你会发现 Vue 3 的响应式系统和 TypeScript 的结合可以创造出既安全又易用的组件。
记住，好的接口设计不是让开发者觉得“好难用”，而是让他们在写代码时感到“好顺畅”。类型安全不是为了限制开发者，而是为了在他们犯错之前就给出提示。
希望这些经验能帮到你。如果你在实战中遇到具体问题，欢迎随时交流！