Components/DrawerForm

DrawerForm

A form in a side drawer for creating or editing records.

VerifiedSince 0.9.2

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 own size sizes its controls.
  • Drawer forms do not autosave. To save as the user edits, put a TxForm with autosave in a TxDrawer.
  • Return a promise from @submit. Return false, throw, or call setErrors(), and the drawer stays open.
  • Outside English, pass submitText, cancelText, messages.leaveConfirm, and drawerProps.closeLabel to name the close button.

API Reference

Props

The TxForm props below apply too: the drawer builds model from initialValues, and autosave does not apply.

PropTypeDefaultDescription
visiblebooleanrequiredShows the drawer. Use with v-model:visible.
titlestring''Drawer title.
initialValuesFormValues-The values the form opens with. Each open edits a copy, so the parent's values change only when the parent changes them.
submitTextstring'Save'Text of the submit button.
cancelTextstring'Cancel'Text of the cancel button.
drawerPropsRecord<string, unknown>-Any other TxDrawer prop, such as size or direction. Closing is asked of the form, not of beforeClose.
idstringgeneratedThe form's id, and the prefix of every field id.
rulesFormRules-Form-level rules keyed by field path.
schemaFormStandardSchema-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.
labelWidthstring | number16emWidest 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.
messagesPartial<FormMessages>-Overrides the built-in text.
size'small' | 'medium' | 'large''medium'Size of the controls inside; the drawer width is drawerProps.size.
disabledbooleanfalseDisables the controls inside that read the form, and blocks submit.
readonlybooleanfalseShows the values as a record: controls can be focused and copied, not changed; no field is marked required.
reconcileFormReconcile-Decides what model holds when fetched values reach fields the user changed.
persistboolean | FormPersistOptionsfalseKeeps what the user typed under id; true takes the defaults.
leaveConfirmFormLeaveConfirm | falsehost's, then window.confirmAsked 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

EventPayloadDescription
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

SlotPropsDescription
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

NameTypeDescription
formTxForm | nullThe 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 model from a copy of initialValues and makes it the baseline, so edits left at closing never carry over to the next open.
  • When initialValues changes 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 TxForm does 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 TxDrawer and TxForm, with beforeClose wired to the form's confirmLeave(). Opening, copying and closing share form/src/use-overlay-form.ts with TxModalForm.
  • The footer sits outside the <form>, and the submit button reaches it through form: 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