组件/ModalForm 弹窗表单

ModalForm 弹窗表单

在对话框里编辑一条记录的表单

Verified自 0.9.2

用法

基础

每次打开都编辑 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 不适用。

属性名类型默认值说明
modelValueboolean必填是否显示,用于 v-model。
titlestring''对话框标题。
widthstring'480px'对话框宽度。
initialValuesFormValues-打开时的值;每次打开编辑一份副本,父级的值只在父级自己修改时变化。
submitTextstring'Save'提交按钮的文字。
cancelTextstring'Cancel'取消按钮的文字。
modalPropsRecord<string, unknown>-其余 TxModal 属性,如 surface、fullscreen;是否关闭由表单决定,不经过 beforeClose。
idstring自动生成表单的 id,也是字段 id 的前缀:<id>-<prop>。
rulesFormRules-以字段路径为 key 的表单级规则。
schemaFormStandardSchema-Standard Schema v1 校验器,校验整个 model;没有对应字段的问题列在错误摘要中。
layout'auto' | 'side' | 'stacked' | 'inline''auto'字段布局。
labelPosition'left' | 'right' | 'top'-layout 的旧写法。
labelAlign'start' | 'end''end'侧边 label 的对齐。
labelWidthstring | number16em侧边 label 列的最大宽度,数字按 px 计。
requiredMark'asterisk' | 'optional' | 'none''asterisk'必填项标星号,选填项标 messages.optional,或都不标。
validateOn'blur' | 'submit''blur'首条消息出现的时机:离开改过的字段时,或首次提交时。
messagesPartial<FormMessages>-覆盖内置文案。
size'small' | 'medium' | 'large''medium'表单内控件的尺寸;对话框宽度见 width。
disabledbooleanfalse禁用表单内读取表单状态的控件,并阻止提交。
readonlybooleanfalse只读展示:控件可聚焦、复制,但不能修改,也不标必填。
reconcileFormReconcile-取回的数据覆盖用户改过的字段时,决定 model 的取值。
persistboolean | FormPersistOptionsfalse以 id 保存用户输入(草稿);true 采用默认设置。
leaveConfirmFormLeaveConfirm | 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 }替换底栏的取消与提交按钮。

暴露方法

名称类型说明
formTxForm | 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