Vue / 系统课时

设计组件接口

设计组件接口

通用组件真正可复用的关键,不是把页面代码搬进组件,而是把稳定能力抽成清晰契约。本课用 Props、事件和插槽划分输入、输出与扩展点,并通过操作面板示例控制组件边界,避免业务规则渗入基础组件。

学习目标

  • 能用 Props、事件和插槽分别表达输入、通知与结构扩展。
  • 能为组件划定职责边界,避免直接依赖页面接口和业务状态。
  • 能通过 TypeScript 类型让调用方获得明确的参数提示。

先确定组件职责

设计接口前,先写清组件“负责什么”和“不负责什么”。通用操作面板可以负责标题、加载态、禁用态、内容布局与按钮区域,但不应负责调用用户保存接口、判断业务权限或跳转路由。这些规则变化频繁,应留在页面层。

可以用三个问题筛选职责:多个页面是否都需要这项能力;能力是否能脱离具体业务命名;调用方是否能够通过稳定参数控制它。只有答案基本为“是”的内容,才适合进入通用组件。

用三类接口划分协作边界

Props 是父组件传入的只读配置,适合标题、状态和展示选项;事件表示组件内部发生了值得外部处理的动作;插槽让父组件提供结构内容,同时由组件保留布局控制权。三者共同形成单向契约,而不是让组件读写外部任意变量。

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 约定交给父组件处理。

当一个插槽需要传递大量零散变量,或一个事件携带整个页面状态时,通常说明组件职责过宽。此时应拆分组件,或把业务组合逻辑移回页面,而不是继续增加参数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计组件接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通