---
title: "ModalForm 弹窗表单"
description: "在对话框里编辑一条记录的表单"
category: Form
status: beta
since: 0.9.2
tags: [form, modal, dialog]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
每次打开都编辑 `initialValues` 的一份副本；提交成功才关闭，有未保存的修改时关闭前先询问。
::::TuffDemoWrapper{demo="ModalFormBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const open = ref(false)
  const member = ref({ name: '林晓', email: 'lin@example.com', role: 'editor' })
  const roles = [
    { value: 'owner', label: '所有者' },
    { value: 'editor', label: '编辑者' },
    { value: 'viewer', label: '查看者' },
  ]
  const rules = {
    name: { required: true, message: '请输入姓名' },
    email: { type: 'email', message: '邮箱格式不正确' },
  }

  // 返回的 Promise 完成前，对话框保持打开，保存按钮显示加载
  async function save(values) {
    await updateMember(values)
    member.value = values
  }
  </script>

  <template>
    <TxButton @click="open = true">编辑</TxButton>
    <TxModalForm
      v-model="open"
      title="编辑成员"
      :initial-values="member"
      :rules="rules"
      :messages="{ leaveConfirm: '有未保存的更改，仍要关闭吗？' }"
      submit-text="保存"
      cancel-text="取消"
      :modal-props="{ closeLabel: '关闭' }"
      @submit="save"
    >
      <template #default="{ model }">
        <TxFormItem label="姓名" prop="name">
          <TuffInput v-model="model.name" />
        </TxFormItem>
        <TxFormItem label="邮箱" prop="email">
          <TuffInput v-model="model.email" type="email" />
        </TxFormItem>
        <TxFormItem label="角色" prop="role">
          <TxSelect v-model="model.role" :options="roles" />
        </TxFormItem>
      </template>
    </TxModalForm>
  </template>
---
::::

### 自定义底栏
`footer` 插槽拿到 `formId`、`submitting` 与 `cancel`；提交按钮用 `form` 属性指向表单，回车与点击走同一次提交。

```vue
<TxModalForm v-model="open" :initial-values="member" @submit="save">
  <template #default="{ model }">…</template>
  <template #footer="{ formId, submitting, cancel }">
    <TxButton variant="danger" :disabled="submitting" @click="remove">删除</TxButton>
    <TxButton :disabled="submitting" @click="cancel">取消</TxButton>
    <TxButton variant="primary" native-type="submit" :form="formId" :loading="submitting">保存</TxButton>
  </template>
</TxModalForm>
```

### 最佳实践

- 只放几项字段；字段多、需要滚动或要对照页面内容时，用 `TxDrawerForm`。
- `@submit` 返回 Promise；返回 `false`、抛出异常或调用 `setErrors()` 时，对话框留在原处。
- 弹窗表单没有自动保存；要边改边存，把带 `autosave` 的 `TxForm` 放进 `TxDrawer`。
- 自定义底栏时用插槽给的 `cancel` 关闭，它和 Escape 一样先询问。
- 非英文界面传入 `submitText`、`cancelText`、`messages.leaveConfirm`，以及右上角关闭按钮的名称 `modalProps.closeLabel`。

## API 参考

### 属性

下列 `TxForm` 属性同样可传入；`model` 由对话框按 `initialValues` 构建，`autosave` 不适用。

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `modelValue` | `boolean` | 必填 | 是否显示，用于 `v-model`。 |
| `title` | `string` | `''` | 对话框标题。 |
| `width` | `string` | `'480px'` | 对话框宽度。 |
| `initialValues` | `FormValues` | - | 打开时的值；每次打开编辑一份副本，父级的值只在父级自己修改时变化。 |
| `submitText` | `string` | `'Save'` | 提交按钮的文字。 |
| `cancelText` | `string` | `'Cancel'` | 取消按钮的文字。 |
| `modalProps` | `Record<string, unknown>` | - | 其余 `TxModal` 属性，如 `surface`、`fullscreen`；是否关闭由表单决定，不经过 `beforeClose`。 |
| `id` | `string` | 自动生成 | 表单的 id，也是字段 id 的前缀：`<id>-<prop>`。 |
| `rules` | `FormRules` | - | 以字段路径为 key 的表单级规则。 |
| `schema` | `FormStandardSchema` | - | Standard Schema v1 校验器，校验整个 `model`；没有对应字段的问题列在错误摘要中。 |
| `layout` | `'auto' \| 'side' \| 'stacked' \| 'inline'` | `'auto'` | 字段布局。 |
| `labelPosition` | `'left' \| 'right' \| 'top'` | - | `layout` 的旧写法。 |
| `labelAlign` | `'start' \| 'end'` | `'end'` | 侧边 label 的对齐。 |
| `labelWidth` | `string \| number` | `16em` | 侧边 label 列的最大宽度，数字按 px 计。 |
| `requiredMark` | `'asterisk' \| 'optional' \| 'none'` | `'asterisk'` | 必填项标星号，选填项标 `messages.optional`，或都不标。 |
| `validateOn` | `'blur' \| 'submit'` | `'blur'` | 首条消息出现的时机：离开改过的字段时，或首次提交时。 |
| `messages` | `Partial<FormMessages>` | - | 覆盖内置文案。 |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 表单内控件的尺寸；对话框宽度见 `width`。 |
| `disabled` | `boolean` | `false` | 禁用表单内读取表单状态的控件，并阻止提交。 |
| `readonly` | `boolean` | `false` | 只读展示：控件可聚焦、复制，但不能修改，也不标必填。 |
| `reconcile` | `FormReconcile` | - | 取回的数据覆盖用户改过的字段时，决定 `model` 的取值。 |
| `persist` | `boolean \| FormPersistOptions` | `false` | 以 `id` 保存用户输入（草稿）；`true` 采用默认设置。 |
| `leaveConfirm` | `FormLeaveConfirm \| false` | 宿主的，其次 `window.confirm` | 带着草稿存不下的修改离开前询问；`false` 从不询问。 |
| `onSubmit` | `(values: FormValues, event?: Event) => unknown` | - | 全部校验通过后调用；返回的 Promise 完成前对话框保持打开，`@submit` 即绑定它。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(value: boolean)` | 打开或关闭时触发。 |
| `submit-success` | `(values: FormValues)` | 提交成功，随后对话框关闭。 |
| `validate` | `(valid: boolean)` | 同 `TxForm`。 |
| `persist-error` | `(error: unknown)` | 同 `TxForm`。 |

### 插槽

| 插槽名 | 参数 | 说明 |
|------|------|------|
| `default` | `{ model, dirty, valid, submitting, submitted, errors, rootError }` | 表单项；`model` 是这次打开编辑的副本。 |
| `footer` | `{ formId, submitting, cancel }` | 替换底栏的取消与提交按钮。 |

### 暴露方法

| 名称 | 类型 | 说明 |
|------|------|------|
| `form` | `TxForm \| null` | 对话框打开时为里面的表单，拥有 `TxForm` 的全部方法；关闭时为 `null`。 |
| `cancel` | `() => Promise<void>` | 与「取消」相同：先就会丢失的修改询问，再关闭。 |

## 概述

- 每次打开都用 `initialValues` 的副本新建 `model` 并以它为基线；关闭后表单随对话框卸载，修改不会带到下一次打开。
- 打开期间 `initialValues` 变化（如记录刚加载完）会成为新的已保存值：没改过的字段换成新值，改过的字段保留修改。
- Escape、遮罩、关闭按钮与「取消」都先经过表单的 `confirmLeave()`，只就草稿存不下的修改询问；提交进行中不能关闭。
- 焦点在 `TxForm` 内按 Escape 不会走到这条路径（见模态框的焦点规则），因此不询问离开。
- 提交成功后先派发 `submit-success`，再关闭。
- 底栏在 `<form>` 之外，提交按钮用 `form` 属性关联表单；在字段里按 Enter 与点击按钮是同一次提交、同一套校验。

## 技术实现

- 由 `TxModal` 与 `TxForm` 组合而成，`beforeClose` 接表单的 `confirmLeave()`；打开、副本与关闭的逻辑与 `TxDrawerForm` 共用 `form/src/use-overlay-form.ts`。
- 源码：`packages/tuffex/packages/components/src/modal-form/`。

<TuffDocSourceLink />
