Vue / 系统课时
设计组件接口
设计组件接口
通用组件真正可复用的关键,不是把页面代码搬进组件,而是把稳定能力抽成清晰契约。本课用 Props、事件和插槽划分输入、输出与扩展点,并通过操作面板示例控制组件边界,避免业务规则渗入基础组件。
学习目标
- 能用 Props、事件和插槽分别表达输入、通知与结构扩展。
- 能为组件划定职责边界,避免直接依赖页面接口和业务状态。
- 能通过 TypeScript 类型让调用方获得明确的参数提示。
先确定组件职责
设计接口前,先写清组件“负责什么”和“不负责什么”。通用操作面板可以负责标题、加载态、禁用态、内容布局与按钮区域,但不应负责调用用户保存接口、判断业务权限或跳转路由。这些规则变化频繁,应留在页面层。
可以用三个问题筛选职责:多个页面是否都需要这项能力;能力是否能脱离具体业务命名;调用方是否能够通过稳定参数控制它。只有答案基本为“是”的内容,才适合进入通用组件。
用三类接口划分协作边界
Props 是父组件传入的只读配置,适合标题、状态和展示选项;事件表示组件内部发生了值得外部处理的动作;插槽让父组件提供结构内容,同时由组件保留布局控制权。三者共同形成单向契约,而不是让组件读写外部任意变量。

实现一个最小通用面板
下面的组件使用类型化 Props、事件和插槽。submit 方法只负责校验当前是否可操作并抛出事件,不包含任何保存逻辑,因此不同页面可以复用同一接口。
vue
<script setup lang="ts">
interface SubmitPayload {
source: 'panel'
}
interface Props {
title: string
loading?: boolean
disabled?: boolean
}
const props = withDefaults(defineProps<Props>(), {
loading: false,
disabled: false
})
const emit = defineEmits<{
submit: [payload: SubmitPayload]
cancel: []
}>()
// 插槽只暴露必要状态和提交入口,避免泄露组件内部实现。
defineSlots<{
default(props: { disabled: boolean }): unknown
actions(props: { submit: () => void; disabled: boolean }): unknown
}>()
const isDisabled = () => props.loading || props.disabled
// 通用组件只发出动作,不在内部调用任何业务接口。
function submit() {
if (isDisabled()) return
emit('submit', { source: 'panel' })
}
function cancel() {
if (isDisabled()) return
emit('cancel')
}
</script>
<template>
<section class="action-panel" :aria-busy="loading">
<header class="action-panel__header">
<h2>{{ title }}</h2>
</header>
<div class="action-panel__body">
<slot :disabled="isDisabled()" />
</div>
<footer class="action-panel__actions">
<slot name="actions" :submit="submit" :disabled="isDisabled()">
<button type="button" :disabled="isDisabled()" @click="submit">
{{ loading ? '处理中' : '提交' }}
</button>
<button type="button" :disabled="isDisabled()" @click="cancel">
取消
</button>
</slot>
</footer>
</section>
</template>预期结果
text
组件渲染标题、默认内容区和操作区。
loading 或 disabled 为 true 时,按钮不可用且不会触发 submit、cancel。
父组件可以替换 actions 插槽,也可以监听 submit、cancel 事件处理业务。父组件只组合业务字段和保存动作。下面是片段示例,依赖上面的 BaseActionPanel.vue。
vue
<script setup lang="ts">
import { ref } from 'vue'
import BaseActionPanel from './BaseActionPanel.vue'
const saving = ref(false)
const username = ref('')
// 页面层组合业务数据,并决定提交后的真实处理方式。
async function save(payload: { source: 'panel' }) {
saving.value = true
console.log('save', payload.source, username.value)
saving.value = false
}
</script>
<template>
<BaseActionPanel title="编辑用户" :loading="saving" @submit="save">
<template #default="{ disabled }">
<input v-model="username" :disabled="disabled" placeholder="用户名" />
</template>
<template #actions="{ submit, disabled }">
<button type="button" :disabled="disabled" @click="submit">
保存用户
</button>
</template>
</BaseActionPanel>
</template>预期结果
text
页面显示“编辑用户”、用户名输入框和“保存用户”按钮。
输入 alice 后点击按钮,控制台输出:save panel alice检查接口是否过度设计
接口命名应描述稳定语义,例如 loading、submit 和 actions,不要使用 mode="user-create" 这类业务模式驱动大量分支。Props 也不应被子组件直接修改;需要变更时,通过事件或 v-model 约定交给父组件处理。
当一个插槽需要传递大量零散变量,或一个事件携带整个页面状态时,通常说明组件职责过宽。此时应拆分组件,或把业务组合逻辑移回页面,而不是继续增加参数。
按自己的节奏,确认真正理解。