ModalForm
A form that edits one record in a dialog.
Usage
Basic
Each open edits a copy of initialValues; the dialog closes once the submit succeeds, and asks before closing on unsaved changes.
Loading demo...
Custom Footer
The footer slot receives formId, submitting and cancel; the submit button points at the form with form, so Enter and a click submit alike.
<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">Delete</TxButton>
<TxButton :disabled="submitting" @click="cancel">Cancel</TxButton>
<TxButton variant="primary" native-type="submit" :form="formId" :loading="submitting">Save</TxButton>
</template>
</TxModalForm>
Best Practices
- Keep it to a few fields. Use
TxDrawerFormfor long forms, forms that scroll, or forms read against the page. - Return a promise from
@submit. Returnfalse, throw, or callsetErrors(), and the dialog stays open. - Modal forms do not autosave. To save as the user edits, put a
TxFormwithautosavein aTxDrawer. - In a custom footer, close with the slot's
cancel: like Escape, it asks first. - Outside English, pass
submitText,cancelText,messages.leaveConfirm, andmodalProps.closeLabelto name the close button.
API Reference
Props
The TxForm props below apply too: the dialog builds model from initialValues, and autosave does not apply.
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | boolean | required | Shows the dialog. Use with v-model. |
title | string | '' | Dialog title. |
width | string | '480px' | Dialog width. |
initialValues | FormValues | - | The values the form opens with. Each open edits a copy, so the parent's values change only when the parent changes them. |
submitText | string | 'Save' | Text of the submit button. |
cancelText | string | 'Cancel' | Text of the cancel button. |
modalProps | Record<string, unknown> | - | Any other TxModal prop, such as surface or fullscreen. Closing is asked of the form, not of beforeClose. |
id | string | generated | The form's id, and the prefix of every field id. |
rules | FormRules | - | Form-level rules keyed by field path. |
schema | FormStandardSchema | - | A Standard Schema v1 validator checked against the whole model; issues with no matching field are listed in the error summary. |
layout | 'auto' | 'side' | 'stacked' | 'inline' | 'auto' | Field layout. |
labelPosition | 'left' | 'right' | 'top' | - | Older spelling of layout. |
labelAlign | 'start' | 'end' | 'end' | Label alignment in the side column. |
labelWidth | string | number | 16em | Widest the side label column may grow; numbers are in pixels. |
requiredMark | 'asterisk' | 'optional' | 'none' | 'asterisk' | Marks required fields with an asterisk, optional fields with messages.optional, or neither. |
validateOn | 'blur' | 'submit' | 'blur' | When the first message appears: on leaving a changed field, or on the first submit. |
messages | Partial<FormMessages> | - | Overrides the built-in text. |
size | 'small' | 'medium' | 'large' | 'medium' | Size of the controls inside; the dialog width is width. |
disabled | boolean | false | Disables the controls inside that read the form, and blocks submit. |
readonly | boolean | false | Shows the values as a record: controls can be focused and copied, not changed; no field is marked required. |
reconcile | FormReconcile | - | Decides what model holds when fetched values reach fields the user changed. |
persist | boolean | FormPersistOptions | false | Keeps what the user typed under id; true takes the defaults. |
leaveConfirm | FormLeaveConfirm | false | host's, then window.confirm | Asked before leaving with changes no draft holds; false never asks. |
onSubmit | (values: FormValues, event?: Event) => unknown | - | Called once every check passes; the dialog stays open until a returned promise settles. @submit binds it. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | (value: boolean) | The dialog opens or closes. |
submit-success | (values: FormValues) | The submit went through; the dialog closes next. |
validate | (valid: boolean) | As on TxForm. |
persist-error | (error: unknown) | As on TxForm. |
Slots
| Slot | Props | Description |
|---|---|---|
default | { model, dirty, valid, submitting, submitted, errors, rootError } | The form items. model is the copy this open edits. |
footer | { formId, submitting, cancel } | Replaces the cancel and submit buttons. |
Exposed Methods
| Name | Type | Description |
|---|---|---|
form | TxForm | null | The form inside while the dialog is open, with every TxForm method; null while it is closed. |
cancel | () => Promise<void> | Closes as Cancel does: the form first asks about changes it would lose. |
Overview
- Each open builds
modelfrom a copy ofinitialValuesand makes it the baseline. Closing unmounts the form with the dialog, so edits never carry over to the next open. - When
initialValueschanges while the dialog is open, as when a record finishes loading, it becomes the saved state: untouched fields take the new values, and fields the user changed keep their edits. - Escape, the mask, the close button and Cancel all go through the form's
confirmLeave(), which asks only about changes no draft holds. A running submit cannot be closed. - Escape with focus inside a
TxFormdoes not reach this path (see the Modal focus rule), so it asks nothing. - A submit that goes through emits
submit-success, then closes. - The footer sits outside the
<form>, and the submit button reaches it throughform: Enter in a field and a click make the same submit with the same checks.
Technologies
- Built from
TxModalandTxForm, withbeforeClosewired to the form'sconfirmLeave(). Opening, copying and closing shareform/src/use-overlay-form.tswithTxDrawerForm. - Source:
packages/tuffex/packages/components/src/modal-form/.
查看源码
packages/tuffex/packages/components/src/modal-form/index.ts