Vue / 系统课时

受控表单状态设计

受控表单状态设计

企业表单真正难的不是绑定输入框,而是让“新建默认值、编辑回显、用户修改、提交数据”始终走同一套可预测的数据流。本节用 Vue 3 与 TypeScript 组织单一表单模型,并把接口对象与提交 DTO 明确隔离。

学习目标

  • 用工厂函数创建稳定、可复用的表单默认值
  • 正确处理编辑回显,避免直接修改接口返回对象
  • 在提交前显式转换表单模型,只发送后端真正需要的字段

把表单模型当成独立状态

表单状态不应直接等同于接口实体。接口对象通常包含 id、时间戳、只读状态等字段,而表单只需要用户可编辑的值。最稳妥的做法是先定义 UserForm,再用工厂函数为每次新建或重置创建完整默认值。

ts
interface UserForm {
  name: string
  email: string
  enabled: boolean
}

function createDefaultForm(): UserForm {
  return {
    name: '',
    email: '',
    enabled: true,
  }
}

这段代码是表单模型片段示例,依赖后续组件中的 reactive 使用。工厂函数比复用同一个对象安全,因为每次调用都会得到新的引用,不会把上一次编辑残留带到下一次。

新建、回显与提交之间的受控表单数据流

用显式映射完成编辑回显

编辑页拿到详情数据后,不要直接写成 form = detail,也不要把整个接口对象塞进表单。使用 Object.assign 或逐字段赋值,把允许编辑的字段复制进既有的响应式对象,既能保留响应式引用,也能控制回显范围。

下面的单文件组件同时覆盖新建默认值、模拟编辑回显、用户修改、重置和提交转换。

vue
<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>

预期结果

text
页面加载后回显 Ada、ada@example.com,启用状态为选中。
点击“提交”后控制台输出:
{"name":"Ada","email":"ada@example.com","enabled":true}
点击“重置”后姓名和邮箱清空,启用状态恢复为选中。

<TIME> 代表动态时间值,实际接口返回会不同。这里最重要的不是 Object.assign 本身,而是回显与提交都经过明确映射,接口字段不会无意间进入可编辑状态或提交参数。

区分重置、回显与提交边界

重置应回到“当前业务定义的默认状态”,而不是简单清空全部字段。编辑回显只负责把详情转成表单值;提交转换则负责清理字符串、标准化格式和剔除只读字段。三个动作职责不同,不要塞进一个万能函数。

如果表单包含日期、金额、枚举或多选项,建议继续保持“接口类型 → 表单类型 → 提交类型”的三层转换。这样页面可以使用最适合交互的值,后端仍收到稳定的数据结构。

避免几个常见失控点

不要直接把 props、Pinia 实体或请求响应对象交给 v-model 修改,这会让局部编辑污染外部状态。不要用不完整对象初始化复杂表单,否则字段在运行期才补齐时更容易出现 undefined 分支。也不要把格式转换散落在每个输入事件里,统一放在回显和提交边界更容易测试。

受控表单设计的核心是:页面只有一个可编辑模型,外部数据进入它时显式映射,离开它时再次显式转换。这样新建、编辑、重置与提交都能围绕同一份稳定状态工作。

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

目录与阅读设置

阅读设置

17

记录一个想法

受控表单状态设计

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

登录哪都通