外观
KvFormDrawer
业务新增表单及新增/编辑共用表单的默认容器。复用 KvDrawer 的布局与主题样式,提供固定操作区、提交锁定和未保存修改确认。默认 mode="drawer",宽度为 720px;使用 mode="page" 时占满视口减去菜单实际占用宽度及 10px 间距后的空间。两种模式均支持小屏全宽。
标题栏为 44px 起,内边距 7px 20px(视口 ≤640px 时为 7px 16px),标题 14px。底部按钮栏内边距统一为 12px 20px,小屏保持一致,按钮 28px 高。桌面左侧圆角 16px,视口 ≤640px 时全宽并取消圆角。正文独立滚动,外观与通用抽屉保持一致。
关闭后重置拖拽宽度,下次打开恢复默认 720px;显式设置 size 或 mode="page" 时恢复对应的初始宽度。
使用
从 @kevairy/components 导入 KvFormDrawer,在应用入口导入一次 @kevairy/components/style.css。完整示例如下:
vue
<template>
<div class="form-drawer-demo-controls">
<ElButton type="primary" @click="visible = true">新增资源</ElButton>
<ElRadioGroup v-model="mode" aria-label="表单抽屉模式">
<ElRadioButton value="page">page 模式</ElRadioButton>
<ElRadioButton value="drawer">drawer 模式(500px)</ElRadioButton>
</ElRadioGroup>
</div>
<KvFormDrawer
v-model="visible"
title="新增资源"
:mode="mode"
:dirty="dirty"
:submitting="submitting"
@submit="save"
@closed="reset"
>
<ElForm
ref="formRef"
:model="form"
:rules="rules"
:disabled="submitting"
label-position="top"
@submit.prevent="save"
>
<ElFormItem label="资源名称" prop="name">
<ElInput v-model="form.name" placeholder="请输入资源名称" />
</ElFormItem>
<ElFormItem label="说明" prop="description">
<ElInput v-model="form.description" type="textarea" :rows="6" />
</ElFormItem>
<ElCheckbox v-model="simulateFailure">模拟保存失败,验证填写内容保留</ElCheckbox>
<ElAlert v-if="error" :title="error" type="error" :closable="false" />
</ElForm>
</KvFormDrawer>
</template>
<script setup lang="ts">
import { computed, reactive, ref } from 'vue'
import {
ElAlert,
ElButton,
ElCheckbox,
ElForm,
ElFormItem,
ElInput,
ElMessage,
ElRadioButton,
ElRadioGroup,
type FormInstance,
type FormRules
} from 'element-plus'
import { KvFormDrawer } from '@kevairy/components'
const visible = ref(false)
const mode = ref<'page' | 'drawer'>('drawer')
const submitting = ref(false)
const simulateFailure = ref(false)
const error = ref('')
const formRef = ref<FormInstance>()
const form = reactive({ name: '', description: '' })
const dirty = computed(() => form.name !== '' || form.description !== '')
const rules: FormRules = {
name: [{ required: true, message: '请输入资源名称', trigger: 'blur' }]
}
const save = async () => {
if (submitting.value) return
submitting.value = true
error.value = ''
try {
if (!(await formRef.value?.validate().catch(() => false))) return
await new Promise((resolve) => window.setTimeout(resolve, 500))
if (simulateFailure.value) throw new Error('保存失败,请重试。填写内容已保留。')
visible.value = false
ElMessage.success('资源已创建(演示数据)')
} catch (cause) {
error.value = cause instanceof Error ? cause.message : '保存失败,请重试'
} finally {
submitting.value = false
}
}
const reset = () => {
Object.assign(form, { name: '', description: '' })
simulateFailure.value = false
error.value = ''
formRef.value?.clearValidate()
}
</script>
<style scoped>
.form-drawer-demo-controls {
display: flex;
flex-wrap: wrap;
gap: 12px;
align-items: center;
}
</style>简单表单可选择紧凑模式,原有提交和关闭保护保持一致:
vue
<KvFormDrawer v-model="visible" title="新增资源" mode="drawer" :dirty="dirty" @submit="save">
<ResourceForm />
</KvFormDrawer>Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue / v-model | boolean | 必填 | 是否打开 |
title | string | 必填 | 抽屉标题及无障碍名称 |
mode | 'page' | 'drawer' | 'drawer' | drawer 默认 720px;page 占满菜单旁的内容区 |
size | number | string | — | 可选显式宽度,优先于 mode 的默认宽度,数字按 px;不超过菜单旁的可用宽度;视口 ≤640px 时全宽 |
resizable | boolean | true | 复用 KvDrawer 的内置左边缘拖拽调宽,最小 500px,不超过可用宽度;小屏全宽时隐藏手柄 |
sidebarWidth | number | string | 布局提供,未提供时 0 | 覆盖菜单实际占用宽度 |
gap | number | 10 | 与菜单之间的间距,px |
headerBackground | string | 主题浅色背景 | 覆盖标题栏背景色 |
closeOnClickModal | boolean | true | 点击抽屉外部遮罩关闭;有修改时先确认,提交期间禁止关闭,可显式设为 false |
submitting | boolean | false | 提交状态,锁定取消、关闭、Esc 和保存按钮 |
submitDisabled | boolean | false | 禁止保存,例如详情加载中或无写权限 |
dirty | boolean | false | 是否有未保存修改,由页面按初始快照计算 |
messages | Partial<FormDrawerMessages> | 中文文案 | 覆盖按钮和放弃修改确认文案 |
messages 字段:cancel(取消)、submit(保存)、discardTitle(放弃修改?)、discardMessage、discardConfirm(放弃修改)、discardCancel(继续编辑)。类型及默认值可分别导入 FormDrawerMessages、defaultFormDrawerMessages。
默认点击抽屉外部遮罩可关闭,与取消、关闭按钮和 Esc 一样经过修改确认;提交期间禁止关闭。需要禁用遮罩关闭时设置 :close-on-click-modal="false"。
固定行为包括右侧打开、挂载到 body、关闭后销毁内容。容器补充属性如 class、aria-label 可透传;固定行为由组件控制,不提供 Element Plus 全量 Props 契约。
Slots
| 插槽 | 参数 | 说明 |
|---|---|---|
default | { submitting: boolean } | 表单字段;页面负责绑定控件禁用状态 |
footer-extra | { submitting: boolean } | 标准“取消 / 保存”之前的附加操作;附加按钮应自行处理禁用状态 |
Events
| 事件 | 参数 | 说明 |
|---|---|---|
update:modelValue | boolean | 更新打开状态 |
submit | 无 | 点击保存;页面负责校验和保存,不自动关闭 |
cancel | 无 | 用户确认取消;取消、关闭按钮和 Esc 统一走该流程 |
open / opened / close / closed | 无 | 抽屉生命周期;在 closed 后重置字段和校验 |
openAutoFocus / closeAutoFocus | 无 | 焦点进入和恢复事件 |
关闭与提交
- 取消、右上角关闭、遮罩和 Esc 统一经过
dirty确认。实例方法requestClose(): Promise<void>供页面的附加取消操作调用,也遵守提交锁定和修改保护。 - 父组件直接设置
v-model = false会跳过放弃修改确认,用于保存成功或明确的外部状态切换;普通取消应调用requestClose()。 submitting应在校验开始前同步置为 true,在 finally 中恢复;提交函数入口还应判断当前状态,防止原生表单提交和按钮点击重复触发。- 校验失败和请求失败时保持打开、保留输入,并由页面提示错误。只有保存成功后关闭并刷新列表。
- 编辑场景先加载数据、建立初始快照,再启用输入和保存;不要把加载数据误判为未保存修改。
标题和操作区保持可见,正文高度不足时独立滚动。小屏全宽,并遵循系统“减少动态效果”设置。业务接入约定见新增表单规范。