Skip to content

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-modelboolean必填是否打开
titlestring必填抽屉标题及无障碍名称
mode'page' | 'drawer''drawer'drawer 默认 720px;page 占满菜单旁的内容区
sizenumber | string—可选显式宽度,优先于 mode 的默认宽度,数字按 px;不超过菜单旁的可用宽度;视口 ≤640px 时全宽
resizablebooleantrue复用 KvDrawer 的内置左边缘拖拽调宽,最小 500px,不超过可用宽度;小屏全宽时隐藏手柄
sidebarWidthnumber | string布局提供,未提供时 0覆盖菜单实际占用宽度
gapnumber10与菜单之间的间距,px
headerBackgroundstring主题浅色背景覆盖标题栏背景色
closeOnClickModalbooleantrue点击抽屉外部遮罩关闭;有修改时先确认,提交期间禁止关闭,可显式设为 false
submittingbooleanfalse提交状态,锁定取消、关闭、Esc 和保存按钮
submitDisabledbooleanfalse禁止保存,例如详情加载中或无写权限
dirtybooleanfalse是否有未保存修改,由页面按初始快照计算
messagesPartial<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:modelValueboolean更新打开状态
submit无点击保存;页面负责校验和保存,不自动关闭
cancel无用户确认取消;取消、关闭按钮和 Esc 统一走该流程
open / opened / close / closed无抽屉生命周期;在 closed 后重置字段和校验
openAutoFocus / closeAutoFocus无焦点进入和恢复事件

关闭与提交 ​

  • 取消、右上角关闭、遮罩和 Esc 统一经过 dirty 确认。实例方法 requestClose(): Promise<void> 供页面的附加取消操作调用,也遵守提交锁定和修改保护。
  • 父组件直接设置 v-model = false 会跳过放弃修改确认,用于保存成功或明确的外部状态切换;普通取消应调用 requestClose()。
  • submitting 应在校验开始前同步置为 true,在 finally 中恢复;提交函数入口还应判断当前状态,防止原生表单提交和按钮点击重复触发。
  • 校验失败和请求失败时保持打开、保留输入,并由页面提示错误。只有保存成功后关闭并刷新列表。
  • 编辑场景先加载数据、建立初始快照,再启用输入和保存;不要把加载数据误判为未保存修改。

标题和操作区保持可见,正文高度不足时独立滚动。小屏全宽,并遵循系统“减少动态效果”设置。业务接入约定见新增表单规范。