DrawerForm
A form in a side drawer for creating or editing records.
Usage
Basic
A drawer keeps the page in view for longer forms; each open edits a copy of initialValues, and the drawer closes once the submit succeeds.
Loading demo...
Loading After Opening
Open the drawer first, and hand the record to initialValues once it arrives; it becomes the saved state, and fields the user has already changed keep their edits.
<script setup lang="ts">
const open = ref(false)
const project = ref()
async function edit(id) {
project.value = undefined
open.value = true
project.value = await fetchProject(id)
}
</script>
<template>
<TxDrawerForm v-model:visible="open" title="Edit project" :initial-values="project" :disabled="!project" @submit="save">
<template #default="{ model }">…</template>
</TxDrawerForm>
</template>
Best Practices
- Use it for forms with many fields, forms that scroll, or forms read against the page. For a few fields, use
TxModalForm. - Set the drawer's width in
drawerProps.size. The form's ownsizesizes its controls. - Drawer forms do not autosave. To save as the user edits, put a
TxFormwithautosavein aTxDrawer. - Return a promise from
@submit. Returnfalse, throw, or callsetErrors(), and the drawer stays open. - Outside English, pass
submitText,cancelText,messages.leaveConfirm, anddrawerProps.closeLabelto name the close button.
API Reference
Props
The TxForm props below apply too: the drawer builds model from initialValues, and autosave does not apply.
| Prop | Type | Default | Description |
|---|---|---|---|
visible | boolean | required | Shows the drawer. Use with v-model:visible. |
title | string | '' | Drawer title. |
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. |
drawerProps | Record<string, unknown> | - | Any other TxDrawer prop, such as size or direction. 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 drawer width is drawerProps.size. |
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 drawer stays open until a returned promise settles. @submit binds it. |
Events
| Event | Payload | Description |
|---|---|---|
update:visible | (value: boolean) | The drawer opens or closes. |
submit-success | (values: FormValues) | The submit went through; the drawer 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. Point the submit button at the form with :form="formId". |
Exposed Methods
| Name | Type | Description |
|---|---|---|
form | TxForm | null | The form inside, with every TxForm method; null until the drawer first opens. |
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, so edits left at closing never carry over to the next open. - When
initialValueschanges while the drawer is open, 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 Drawer focus rule), so it asks nothing. - After its first open the drawer keeps its content, and the form with it. Closed, it has nothing left to lose, so reloading the page does not ask.
- A submit that goes through emits
submit-success, then closes.
Technologies
- Built from
TxDrawerandTxForm, withbeforeClosewired to the form'sconfirmLeave(). Opening, copying and closing shareform/src/use-overlay-form.tswithTxModalForm. - The footer sits outside the
<form>, and the submit button reaches it throughform: Enter in a field and a click make the same submit. - Source:
packages/tuffex/packages/components/src/drawer-form/.
查看源码
packages/tuffex/packages/components/src/drawer-form/index.ts