ModalForm 弹窗表单
在对话框里编辑一条记录的表单
用法
基础
每次打开都编辑 initialValues 的一份副本;提交成功才关闭,有未保存的修改时关闭前先询问。
Loading demo...
自定义底栏
footer 插槽拿到 formId、submitting 与 cancel;提交按钮用 form 属性指向表单,回车与点击走同一次提交。
<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/。
查看源码
packages/tuffex/packages/components/src/modal-form/index.ts