Vue / 系统课时
受控表单状态设计
受控表单状态设计
企业表单真正难的不是绑定输入框,而是让“新建默认值、编辑回显、用户修改、提交数据”始终走同一套可预测的数据流。本节用 Vue 3 与 TypeScript 组织单一表单模型,并把接口对象与提交 DTO 明确隔离。
学习目标
- 用工厂函数创建稳定、可复用的表单默认值
- 正确处理编辑回显,避免直接修改接口返回对象
- 在提交前显式转换表单模型,只发送后端真正需要的字段
把表单模型当成独立状态
表单状态不应直接等同于接口实体。接口对象通常包含 id、时间戳、只读状态等字段,而表单只需要用户可编辑的值。最稳妥的做法是先定义 UserForm,再用工厂函数为每次新建或重置创建完整默认值。
interface UserForm {
name: string
email: string
enabled: boolean
}
function createDefaultForm(): UserForm {
return {
name: '',
email: '',
enabled: true,
}
}这段代码是表单模型片段示例,依赖后续组件中的 reactive 使用。工厂函数比复用同一个对象安全,因为每次调用都会得到新的引用,不会把上一次编辑残留带到下一次。

用显式映射完成编辑回显
编辑页拿到详情数据后,不要直接写成 form = detail,也不要把整个接口对象塞进表单。使用 Object.assign 或逐字段赋值,把允许编辑的字段复制进既有的响应式对象,既能保留响应式引用,也能控制回显范围。
下面的单文件组件同时覆盖新建默认值、模拟编辑回显、用户修改、重置和提交转换。
<script setup lang="ts">
import { onMounted, reactive } from 'vue'
interface UserDetail {
id: number
name: string
email: string
enabled: boolean
createdAt: string
}
interface UserForm {
name: string
email: string
enabled: boolean
}
interface UpdateUserPayload {
name: string
email: string
enabled: boolean
}
function createDefaultForm(): UserForm {
return { name: '', email: '', enabled: true }
}
const form = reactive<UserForm>(createDefaultForm())
async function fetchDetail(): Promise<UserDetail> {
return {
id: 42,
name: 'Ada',
email: 'ada@example.com',
enabled: true,
createdAt: '<TIME>',
}
}
function fillForm(detail: UserDetail) {
Object.assign(form, {
name: detail.name,
email: detail.email,
enabled: detail.enabled,
})
}
function resetForm() {
Object.assign(form, createDefaultForm())
}
function toPayload(): UpdateUserPayload {
return {
name: form.name.trim(),
email: form.email.trim().toLowerCase(),
enabled: form.enabled,
}
}
function submit() {
console.log(JSON.stringify(toPayload()))
}
onMounted(async () => {
fillForm(await fetchDetail())
})
</script>
<template>
<form @submit.prevent="submit">
<input v-model="form.name" aria-label="name" />
<input v-model="form.email" aria-label="email" />
<label><input v-model="form.enabled" type="checkbox" /> 启用</label>
<button type="submit">提交</button>
<button type="button" @click="resetForm">重置</button>
</form>
</template>预期结果
页面加载后回显 Ada、ada@example.com,启用状态为选中。
点击“提交”后控制台输出:
{"name":"Ada","email":"ada@example.com","enabled":true}
点击“重置”后姓名和邮箱清空,启用状态恢复为选中。<TIME> 代表动态时间值,实际接口返回会不同。这里最重要的不是 Object.assign 本身,而是回显与提交都经过明确映射,接口字段不会无意间进入可编辑状态或提交参数。
区分重置、回显与提交边界
重置应回到“当前业务定义的默认状态”,而不是简单清空全部字段。编辑回显只负责把详情转成表单值;提交转换则负责清理字符串、标准化格式和剔除只读字段。三个动作职责不同,不要塞进一个万能函数。
如果表单包含日期、金额、枚举或多选项,建议继续保持“接口类型 → 表单类型 → 提交类型”的三层转换。这样页面可以使用最适合交互的值,后端仍收到稳定的数据结构。
避免几个常见失控点
不要直接把 props、Pinia 实体或请求响应对象交给 v-model 修改,这会让局部编辑污染外部状态。不要用不完整对象初始化复杂表单,否则字段在运行期才补齐时更容易出现 undefined 分支。也不要把格式转换散落在每个输入事件里,统一放在回显和提交边界更容易测试。
受控表单设计的核心是:页面只有一个可编辑模型,外部数据进入它时显式映射,离开它时再次显式转换。这样新建、编辑、重置与提交都能围绕同一份稳定状态工作。