Vue / 系统课时
受控组件与无头组件
受控组件与无头组件
当一个业务组件既维护状态、又处理交互、还承担具体样式时,复用往往会被 UI 细节卡住。本节用 Vue 3 与 TypeScript 拆开状态、行为和展示,分别实现受控组件与无头组件,并明确两种模式在企业组件设计中的边界。
学习目标
- 能用
modelValue与update:modelValue设计受控组件接口。 - 能用作用域插槽把状态与行为暴露给调用方,构建无头组件。
- 能根据复用需求判断何时保留默认展示、何时彻底交出渲染控制权。
先拆开状态、行为与展示
受控组件把“状态归谁管”说清楚:父组件持有真实值,子组件只根据输入渲染,并通过事件请求父组件更新。无头组件进一步把“怎么展示”也交给调用方,组件本身主要负责状态机、交互规则和可复用行为。

这两个模式不是竞争关系。受控组件优先解决“状态可预测”,无头组件优先解决“展示可替换”。一个组件也可以同时支持二者,例如内部不保存选中值,只暴露交互逻辑和插槽参数。
设计一个受控开关
下面的组件不保存最终开关状态,而是把 modelValue 当作唯一数据源。点击时只发出变更请求,这样父组件可以统一做权限校验、表单持久化或跨组件联动。以下为片段示例,需放入 ControlledSwitch.vue,并由父组件引入。
<script setup lang="ts">
const props = defineProps<{
modelValue: boolean
disabled?: boolean
}>()
const emit = defineEmits<{
'update:modelValue': [value: boolean]
}>()
function toggle() {
if (props.disabled) return
emit('update:modelValue', !props.modelValue)
}
</script>
<template>
<button
type="button"
:disabled="disabled"
:aria-pressed="modelValue"
@click="toggle"
>
{{ modelValue ? '已开启' : '已关闭' }}
</button>
</template>父组件直接使用 v-model。以下为片段示例,假设 ControlledSwitch.vue 与当前页面可正常解析:
<script setup lang="ts">
import { ref } from 'vue'
import ControlledSwitch from './ControlledSwitch.vue'
const enabled = ref(false)
</script>
<template>
<ControlledSwitch v-model="enabled" />
<p>当前状态:{{ enabled ? '开启' : '关闭' }}</p>
</template>预期结果
初始显示:已关闭 / 当前状态:关闭
点击按钮后:已开启 / 当前状态:开启实际页面不会产生额外中间状态;子组件请求更新后,父组件的新值再通过 modelValue 回流。若父组件拒绝更新,子组件也不会自行进入一个与外部不一致的状态。
把展示交给调用方
当不同业务页面想复用同一套交互规则,但按钮、标签、图标和布局完全不同,可以把组件做成无头形式。下面的 HeadlessToggle 只提供状态与操作,不输出固定 UI。以下为片段示例,需保存为 HeadlessToggle.vue。
<script setup lang="ts">
import { ref } from 'vue'
const open = ref(false)
function toggle() {
open.value = !open.value
}
function setOpen(value: boolean) {
open.value = value
}
</script>
<template>
<slot
:open="open"
:toggle="toggle"
:set-open="setOpen"
/>
</template>调用方通过作用域插槽决定最终渲染。以下为片段示例,假设 HeadlessToggle.vue 已可被当前页面导入:
<script setup lang="ts">
import HeadlessToggle from './HeadlessToggle.vue'
</script>
<template>
<HeadlessToggle v-slot="{ open, toggle }">
<button type="button" @click="toggle">
{{ open ? '收起详情' : '展开详情' }}
</button>
<section v-if="open">
这里完全由业务页面决定结构和样式。
</section>
</HeadlessToggle>
</template>预期结果
初始只显示“展开详情”按钮。
点击后按钮文字变为“收起详情”,并显示详情区域。
再次点击后详情区域隐藏。这里复用的是“布尔状态 + 切换行为”,而不是一套固定 DOM。对于下拉菜单、Tabs、弹层触发器、可选择列表等需要高度定制外观的场景,这种模式尤其有效。
选择合适的接口边界
如果业务只需要统一视觉、允许父组件接管值,优先使用受控组件:API 更短,调用成本也更低。如果不同页面需要完全不同的结构与样式,而交互规则稳定,则适合无头组件。
企业组件常见的组合方式是:底层做无头行为层,上层再封装一个带默认样式的受控组件。这样既能给大多数业务提供开箱即用的界面,也能给少数复杂场景保留彻底定制的入口。