DialogForm 对话框表单

基于 uniboot-ui 的 UDialog / UDrawer 与 UForm 封装的 弹层表单：通过 variant 选择 居中对话框 或 侧滑抽屉，共用同一套 fields、校验、onFinish、描述区与插槽。默认 variant="dialog"。

TIP

由 uniboot-ui 提供；import { DialogForm } from 'uniboot-ui'。模板中可使用 <dialog-form />。包内仍导出 DrawerForm / <drawer-form /> 作为 variant="drawer" 的便捷封装（可选）。

何时使用

需要 弹窗或抽屉 + 配置化字段，而不希望手写整页 UFormItem 时。
提交逻辑为 异步接口：希望在 onFinish 内统一处理 loading、成功关闭、失败保持打开。

`variant`：对话框与抽屉

`variant` 值	容器	说明
`dialog`（默认）	`UDialog`	透传 `width`；表单区为双列 Grid，小屏单列。
`drawer`	`UDrawer`	透传 `size`、`direction`；表单栅格由 `columns`（`1` \| `2`）控制；底部可选 `footerTopBorder`。

两种模式下 打开重置模型、finish / onFinish、return false 不关闭、loading \|\| submitting 等行为一致。文档示例均可在 对话框 / 抽屉 间切换预览。

切换 对话框 / 抽屉 后打开同一表单，提交结果用消息区分。

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { DialogForm, UButton, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

const fields: DialogFormField[] = [
  { key: 'name', label: '名称', required: true },
  {
    key: 'type',
    label: '类型',
    type: 'select',
    required: true,
    options: [
      { label: '类型 A', value: 'a' },
      { label: '类型 B', value: 'b' },
    ],
  },
]

const initialValues = reactive<DialogFormValues>({
  name: '',
  type: '',
})

async function onFinish(values: DialogFormValues) {
  UMessage.success(
    variant.value === 'drawer'
      ? `抽屉提交：${JSON.stringify(values)}`
      : `弹窗提交：${JSON.stringify(values)}`
  )
}
</script>

<template>
  <div class="dialog-form-variant-demo">
    <div class="dialog-form-variant-demo__toolbar">
      <span class="dialog-form-variant-demo__label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">打开表单</u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="同一套 fields"
      description="通过 variant 切换 UDialog / UDrawer，字段与校验逻辑不变。"
      :fields="fields"
      :initial-values="initialValues"
      :on-finish="onFinish"
    />
  </div>
</template>

<style scoped>
.dialog-form-variant-demo {
  padding: 20px;
}

.dialog-form-variant-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}

.dialog-form-variant-demo__label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

显示与提交流程

使用 v-model:visible 控制显隐；每次打开时会根据 fields 与 initialValues 重置内部表单模型。
点击确定：先走 uniboot-ui 表单校验，通过后依次 emit('finish', values)、再执行 onFinish（若传入）。
onFinish 返回 false 或 Promise<false> 时 不关闭 当前弹层；返回 true、undefined 或未定义返回值时关闭（与内部 undefined 结果一致）。
确定按钮 的 loading 为 loading || submitting：submitting 在 onFinish 为 Promise 期间为 true；也可由父组件通过 loading 单独控制。

基础用法

fields 配置列；onFinish 处理提交（可 async）。

新增员工：含描述文案、多字段与 @finish / @cancel 示例。

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

// 表单字段配置
const fields: DialogFormField[] = [
  {
    key: 'name',
    label: '姓名',
    type: 'input',
    placeholder: '请输入姓名',
    required: true,
  },
  {
    key: 'email',
    label: '邮箱',
    type: 'input',
    placeholder: '请输入邮箱',
    required: true,
  },
  {
    key: 'department',
    label: '部门',
    type: 'select',
    placeholder: '请选择部门',
    required: true,
    options: [
      { label: '技术部', value: 'tech' },
      { label: '产品部', value: 'product' },
      { label: '设计部', value: 'design' },
      { label: '市场部', value: 'marketing' },
    ],
  },
  {
    key: 'joinDate',
    label: '入职日期',
    type: 'date',
    placeholder: '请选择入职日期',
  },
  {
    key: 'phone',
    label: '手机号',
    type: 'input',
    placeholder: '请输入手机号',
  },
  {
    key: 'position',
    label: '职位',
    type: 'input',
    placeholder: '请输入职位',
  },
]

// 初始值
const initialValues = reactive<DialogFormValues>({
  name: '',
  email: '',
  department: '',
  joinDate: '',
  phone: '',
  position: '',
})

// 提交处理
async function onFinish(values: DialogFormValues) {
  console.log('提交的数据:', values)

  // 模拟异步请求
  return new Promise<boolean>((resolve) => {
    setTimeout(() => {
      console.log('提交成功')
      UMessage.success('提交成功')
      resolve(true)
    }, 1000)
  })
}

function handleFinish(values: DialogFormValues) {
  console.log('表单校验通过，准备提交:', values)
}

function handleCancel() {
  console.log('取消操作')
}
</script>

<template>
  <div class="dialog-form-demo">
    <div class="dialog-form-demo__toolbar">
      <span class="dialog-form-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">打开表单</u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="新增员工"
      description="请填写员工的基本信息，带 * 号为必填项"
      :fields="fields"
      :initial-values="initialValues"
      confirm-text="确定"
      cancel-text="取消"
      :width="720"
      :on-finish="onFinish"
      @finish="handleFinish"
      @cancel="handleCancel"
    />
  </div>
</template>

<style scoped>
.dialog-form-demo {
  padding: 20px;
}

.dialog-form-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

字段类型

type 省略时等价于 input。下拉须配置 options。

type	说明	控件
`input`	单行文本	`UInput`
`select`	下拉	`USelect`
`date`	日期	`UDatePicker`
`textarea`	多行文本	`UInput` type="textarea"
`number`	数字	`UInput` type="number"

展示各 type；提交成功使用 UMessage.success 提示。

vue

<script setup lang="ts">
import { ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

// 包含所有字段类型的配置
const fields: DialogFormField[] = [
  {
    key: 'title',
    label: '标题',
    type: 'input',
    placeholder: '请输入标题',
    required: true,
  },
  {
    key: 'category',
    label: '分类',
    type: 'select',
    placeholder: '请选择分类',
    required: true,
    options: [
      { label: '技术文章', value: 'tech' },
      { label: '产品文档', value: 'product' },
      { label: '设计资源', value: 'design' },
    ],
  },
  {
    key: 'publishDate',
    label: '发布日期',
    type: 'date',
    placeholder: '请选择发布日期',
    required: true,
  },
  {
    key: 'priority',
    label: '优先级',
    type: 'number',
    placeholder: '请输入优先级（1-10）',
  },
  {
    key: 'description',
    label: '详细描述',
    type: 'textarea',
    placeholder: '请输入详细描述',
  },
]

async function onFinish(values: DialogFormValues) {
  console.log('提交的数据:', values)

  return new Promise((resolve) => {
    setTimeout(() => {
      UMessage.success('创建成功')
      resolve(true)
    }, 800)
  })
}
</script>

<template>
  <div class="dialog-form-types-demo">
    <div class="dialog-form-types-demo__toolbar">
      <span class="dialog-form-types-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">创建项目</u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="创建新项目"
      description="请填写项目的基本信息"
      :fields="fields"
      confirm-text="创建"
      cancel-text="取消"
      :on-finish="onFinish"
    />
  </div>
</template>

<style scoped>
.dialog-form-types-demo {
  padding: 20px;
}

.dialog-form-types-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-types-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

初始值与编辑

initialValues 为 Record<string, unknown>，键与 fields[].key 对应；未提供的键会初始化为空字符串 ''。

打开即回显姓名、邮箱、部门，保存后提示成功。

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

const fields: DialogFormField[] = [
  {
    key: 'name',
    label: '姓名',
    required: true,
    placeholder: '请输入姓名',
  },
  {
    key: 'email',
    label: '邮箱',
    required: true,
    placeholder: '请输入邮箱',
  },
  {
    key: 'department',
    label: '部门',
    type: 'select',
    required: true,
    placeholder: '请选择部门',
    options: [
      { label: '技术部', value: 'tech' },
      { label: '产品部', value: 'product' },
      { label: '设计部', value: 'design' },
    ],
  },
]

/** 模拟从接口拉取后的回显数据 */
const initialValues = reactive<DialogFormValues>({
  name: '李娜',
  email: 'lina@example.com',
  department: 'tech',
})

async function onFinish(values: DialogFormValues) {
  await new Promise((resolve) => setTimeout(resolve, 600))
  console.log('保存:', values)
  UMessage.success('已保存')
  return true
}
</script>

<template>
  <div class="dialog-form-edit-demo">
    <div class="dialog-form-edit-demo__toolbar">
      <span class="dialog-form-edit-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">
        编辑员工（带初始值）
      </u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="编辑员工"
      description="以下为当前档案信息，修改后点击确定保存。"
      :fields="fields"
      :initial-values="initialValues"
      confirm-text="保存"
      cancel-text="取消"
      :on-finish="onFinish"
    />
  </div>
</template>

<style scoped>
.dialog-form-edit-demo {
  padding: 20px;
}

.dialog-form-edit-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-edit-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

提交失败时保持打开

业务错误（如唯一键冲突）时 return false，弹层保持打开，便于用户修改后再次提交。

首次提交模拟冲突；再次提交成功。

vue

<script setup lang="ts">
import { ref, watch } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')
/** 第一次提交模拟业务失败，返回 false 保持弹窗打开 */
const simulateConflict = ref(true)

watch(visible, (v) => {
  if (v) simulateConflict.value = true
})

const fields: DialogFormField[] = [
  {
    key: 'projectCode',
    label: '项目编号',
    required: true,
    placeholder: '请输入唯一编号',
  },
]

async function onFinish(_values: DialogFormValues) {
  await new Promise((resolve) => setTimeout(resolve, 400))
  if (simulateConflict.value) {
    simulateConflict.value = false
    UMessage.warning('该编号已被占用，请修改后再次提交')
    return false
  }
  UMessage.success('提交成功')
  return true
}
</script>

<template>
  <div class="dialog-form-submit-demo">
    <div class="dialog-form-submit-demo__toolbar">
      <span class="dialog-form-submit-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">
        新建项目（提交保持打开）
      </u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="新建项目"
      description="首次点击「确定」将模拟编号冲突：当前弹层不关闭；修改编号后再次提交即可成功。"
      :fields="fields"
      confirm-text="确定"
      cancel-text="取消"
      :on-finish="onFinish"
    />
  </div>
</template>

<style scoped>
.dialog-form-submit-demo {
  padding: 20px;
}

.dialog-form-submit-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-submit-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

描述区：`description` 与插槽

description 属性：展示内置信息条样式（图标 + 文案）。
#description 插槽：完全自定义 描述区内容；只要提供了该插槽，就不再使用 description 属性。

使用 #description 自定义布局与样式。

承载

vue

<script setup lang="ts">
import { ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

const fields: DialogFormField[] = [
  {
    key: 'username',
    label: '用户名',
    type: 'input',
    placeholder: '请输入用户名',
    required: true,
  },
  {
    key: 'email',
    label: '邮箱',
    type: 'input',
    placeholder: '请输入邮箱',
    required: true,
  },
  {
    key: 'role',
    label: '角色',
    type: 'select',
    placeholder: '请选择角色',
    options: [
      { label: '管理员', value: 'admin' },
      { label: '普通用户', value: 'user' },
      { label: '访客', value: 'guest' },
    ],
  },
]

async function onFinish(values: DialogFormValues) {
  console.log('提交的数据:', values)

  return new Promise<boolean>((resolve) => {
    setTimeout(() => {
      UMessage.success('创建成功')
      resolve(true)
    }, 800)
  })
}
</script>

<template>
  <div class="dialog-form-custom-description-demo">
    <div class="dialog-form-custom-description-demo__toolbar">
      <span class="dialog-form-custom-description-demo__variant-label"
        >承载</span
      >
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">
        创建用户（自定义描述）
      </u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="创建新用户"
      :fields="fields"
      :on-finish="onFinish"
    >
      <template #description>
        <div class="custom-description">
          <svg
            viewBox="0 0 24 24"
            width="20"
            height="20"
            fill="none"
            stroke="#67c23a"
            stroke-width="2"
          >
            <circle cx="12" cy="12" r="10" />
            <path
              d="M8 12l3 3 5-5"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
          <div class="custom-description-content">
            <strong>重要提示：</strong>
            <p>请确保填写的信息准确无误，创建后将无法修改用户名。</p>
          </div>
        </div>
      </template>
    </dialog-form>
  </div>
</template>

<style scoped>
.dialog-form-custom-description-demo {
  padding: 20px;
}

.dialog-form-custom-description-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-custom-description-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}

.custom-description {
  display: flex;
  align-items: flex-start;
  gap: 12px;
  padding: 12px 16px;
  background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%);
  border-left: 4px solid #67c23a;
  border-radius: 6px;
}

.custom-description-content {
  flex: 1;
}

.custom-description-content strong {
  color: #67c23a;
  font-size: 14px;
}

.custom-description-content p {
  margin: 4px 0 0;
  color: #606266;
  font-size: 13px;
  line-height: 1.6;
}
</style>

布局说明

variant="dialog"：表单区域为 双列 CSS Grid（repeat(2, 1fr)），表单项自上而下、从左到右填充；视口宽度 ≤ 768px 时为单列。
variant="drawer"：由 columns 控制 1 单列或 2 双列（双列时小屏同样降为单列）。
某项需在双列下 独占一行 时，在该字段上设置 colSpan: 2（例如备注、长文本域）。

双列中「备注」使用 colSpan: 2 占满一行。

vue

<script setup lang="ts">
import { ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

const fields: DialogFormField[] = [
  { key: 'code', label: '编码', required: true, placeholder: '如 PRJ-001' },
  { key: 'name', label: '名称', required: true, placeholder: '项目名称' },
  {
    key: 'remark',
    label: '备注',
    type: 'textarea',
    placeholder: '双列布局下本项独占一行，适合较长说明',
    colSpan: 2,
  },
  { key: 'owner', label: '负责人', placeholder: '姓名' },
  { key: 'dept', label: '所属部门', placeholder: '部门' },
]

async function onFinish(values: DialogFormValues) {
  console.log(values)
  UMessage.success('已提交')
  return true
}
</script>

<template>
  <div class="dialog-form-col-span-demo">
    <div class="dialog-form-col-span-demo__toolbar">
      <span class="dialog-form-col-span-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true"
        >打开表单（备注独占一行）</u-button
      >
    </div>
    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="项目信息"
      description="前两列为常规半宽字段；「备注」使用 colSpan: 2 占满整行。"
      :fields="fields"
      :on-finish="onFinish"
    />
  </div>
</template>

<style scoped>
.dialog-form-col-span-demo {
  padding: 20px;
}

.dialog-form-col-span-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-col-span-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}
</style>

自定义表单项：`#field-{key}` 插槽

当某一列需要 输入框 + 附属操作（如校验、复制、扫码）等组合布局时，可为该字段提供 #field-{key} 插槽，完全替换该项的默认控件；UFormItem 的标签与校验 prop 仍由 fields 配置，与内置渲染一致。

插槽名与字段 key 对应：例如 key: 'kcv' 时使用 #field-kcv；key: 'externalKeyRef' 时使用 #field-externalKeyRef。
作用域参数：model 为表单响应式对象（可与 v-model="model.xxx" 双向绑定）；field 为当前字段配置项。

与示意图一致：双列表单项 + KCV 行内 输入框 +「检验」主按钮（其余列仍走配置化渲染）。

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { Search } from '@uniboot/icons-vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type {
  DialogFormField,
  DialogFormValues,
  DialogFormVariant,
} from 'uniboot-ui'

const visible = ref(false)
const variant = ref<DialogFormVariant>('dialog')

const fields: DialogFormField[] = [
  {
    key: 'algorithm',
    label: '加密算法',
    type: 'select',
    required: true,
    placeholder: '请选择加密算法',
    options: [
      { label: 'AES-256-GCM', value: 'aes256gcm' },
      { label: '3DES', value: '3des' },
    ],
  },
  {
    key: 'bdkId',
    label: 'BDK ID',
    type: 'input',
    required: true,
    placeholder: '请输入 BDK ID',
  },
  {
    key: 'externalKeyRef',
    label: 'externalKeyRef',
    type: 'input',
    required: true,
    placeholder: '请输入 externalKeyRef',
  },
  {
    key: 'kcv',
    label: 'KCV',
    type: 'input',
    required: true,
    placeholder: '请输入 KCV',
  },
]

const initialValues = reactive<DialogFormValues>({
  algorithm: '',
  bdkId: '',
  externalKeyRef: '',
  kcv: '',
})

function handleVerifyKcv(model: DialogFormValues) {
  const v = String(model.kcv ?? '').trim()
  if (!v) {
    UMessage.warning('请先填写 KCV')
    return
  }
  UMessage.success(`KCV 校验通过：${v}`)
}

async function onFinish(_values: DialogFormValues) {
  UMessage.success('新增申请已提交')
  return true
}
</script>

<template>
  <div class="dialog-form-demo">
    <div class="dialog-form-demo__toolbar">
      <span class="dialog-form-demo__variant-label">承载</span>
      <u-button
        size="small"
        :type="variant === 'dialog' ? 'primary' : 'default'"
        @click="variant = 'dialog'"
      >
        对话框
      </u-button>
      <u-button
        size="small"
        :type="variant === 'drawer' ? 'primary' : 'default'"
        @click="variant = 'drawer'"
      >
        抽屉
      </u-button>
      <u-button type="primary" @click="visible = true">新增 DATA Key</u-button>
    </div>

    <dialog-form
      v-model:visible="visible"
      :variant="variant"
      title="新增 DATA Key"
      :fields="fields"
      :initial-values="initialValues"
      confirm-text="新增申请"
      cancel-text="取消"
      :width="640"
      :on-finish="onFinish"
    >
      <template #field-kcv="{ model }">
        <div class="kcv-row">
          <u-input
            v-model="model.kcv"
            class="kcv-input"
            placeholder="请输入 KCV"
          />
          <u-button type="primary" @click="handleVerifyKcv(model)">
            <u-icon class="kcv-btn-icon"><Search /></u-icon>
            检验
          </u-button>
        </div>
      </template>
    </dialog-form>
  </div>
</template>

<style scoped>
.dialog-form-demo {
  padding: 20px;
}

.dialog-form-demo__toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.dialog-form-demo__variant-label {
  font-size: 14px;
  color: var(--u-text-color-regular);
}

.kcv-row {
  display: flex;
  align-items: center;
  gap: 8px;
  width: 100%;
}

.kcv-input {
  flex: 1;
  min-width: 0;
}

.kcv-btn-icon {
  margin-right: 4px;
  vertical-align: middle;
}
</style>

自定义校验

除 required: true 外，可通过 rules 传入与 UForm 一致的规则数组；若同时 required，内置必填规则会排在前面。

import type { DialogFormField } from 'uniboot-ui'

const fields: DialogFormField[] = [
  {
    key: 'email',
    label: '邮箱',
    required: true,
    rules: [{ type: 'email', message: '请输入正确邮箱', trigger: 'blur' }],
  },
]

DialogForm 属性

名称	说明	类型	默认值
variant	承载方式：`dialog` 对话框，`drawer` 抽屉	`enum`	`dialog`
visible	是否显示，使用 `v-model:visible`	`boolean`	`false`
title	标题	`string`	`标题文本`
description	描述文案（表单上方信息条）；与 `#description` 插槽互斥，有插槽时忽略属性	`string`	`''`
fields	表单字段配置	`array`	`[]`
initialValues	打开时的初始值	`object`	`{}`
loading	确定按钮额外 loading（会与内部提交态叠加）	`boolean`	`false`
confirmText	确定按钮文案	`string`	`确定`
cancelText	取消按钮文案	`string`	`取消`
onFinish	校验通过后的提交回调；返回 `false` 时不关闭	`Function`	—
width	`variant="dialog"` 时：宽度，透传 `UDialog`	`string` / `number`	`720`
size	`variant="drawer"` 时：尺寸，透传 `UDrawer`	`string` / `number`	`520`
direction	`variant="drawer"` 时：打开方向，透传 `UDrawer`	`enum`	`rtl`
columns	`variant="drawer"` 时：表单栅格列数 `1` 单列 / `2` 双列	`enum`	`2`
footerTopBorder	`variant="drawer"` 时：底部操作区顶部分隔线	`boolean`	`true`
showClose	是否显示右上角关闭按钮	`boolean`	`true`

事件

名称	说明	类型
finish	校验通过后、调用 `onFinish` 之前触发，参数为当前表单值	`Function`
cancel	用户取消或关闭时触发（如点击取消、关闭图标等）	`Function`
update:visible	显隐变化	`Function`

插槽

名称	说明
description	自定义描述区域；存在时不使用 `description` 属性
`field-{key}`	覆盖 `fields` 中对应 `key` 的控件区（不含标签）；作用域参数 `model`、`field`（见上文「自定义表单项」）
footer	自定义底部操作区；未提供时为默认「取消 + 确定」。提供插槽即整区替换，可通过作用域参数调用提交/取消（见下表）

`footer` 作用域参数

参数	说明
submit	与默认「确定」相同：校验通过后执行 `finish` / `onFinish` 及关闭逻辑
cancel	与默认「取消」相同：关闭并触发 `cancel` 事件
loading	提交中状态（`loading` 与内部 `submitting` 的合并结果），用于主按钮 loading

vue

<dialog-form
  v-model:visible="visible"
  title="编辑"
  :fields="fields"
  :on-finish="onFinish"
>
  <template #footer="{ submit, cancel, loading }">
    <div style="display: flex; justify-content: flex-end; gap: 12px; padding-top: 12px">
      <u-button @click="cancel">放弃</u-button>
      <u-button type="primary" :loading="loading" @click="submit">保存</u-button>
    </div>
  </template>
</dialog-form>

DialogFormField

名称	说明	类型	必填
key	字段唯一标识（表单 model 的键）	`string`	是
label	标签文案	`string`	是
type	字段类型，见上表	`enum`	否
placeholder	占位符	`string`	否
required	是否必填（生成一条默认 `blur` 规则）	`boolean`	否
rules	追加/自定义规则（与 `UForm` FormRules 一致）	`array`	否
options	`type === 'select'` 时的选项	`array`	否
colSpan	双列下横向占位：`1` 占半行，`2` 独占一行（占满整行）；小屏单列时与 `1` 相同	`enum`	否（默认 `1`）

DialogFormValues

表单值类型：object（各字段实际类型由控件决定，如日期可能为字符串或 Date，与 uniboot-ui 行为一致）。

DialogFormFinishResult

enum

返回 false：不关闭当前弹层（对话框或抽屉）。
返回 true 或 undefined / 未 return：关闭当前弹层。

DialogFormOnFinish

type DialogFormOnFinish = (
  values: DialogFormValues
) => Promise<DialogFormFinishResult> | DialogFormFinishResult

`DrawerForm`（可选）

仍可从 uniboot-ui 导入 DrawerForm，等价于 <dialog-form variant="drawer" />。类型 DrawerFormField 等与 DialogFormField 相同（别名）。

DialogFormVariant

enum — DialogForm 的 variant 属性类型，由 uniboot-ui 导出。

代码片段（最小示例）

vue

<script setup lang="ts">
import { ref } from 'vue'
import { DialogForm, UMessage } from 'uniboot-ui'

import type { DialogFormField, DialogFormValues } from 'uniboot-ui'

const visible = ref(false)

const fields: DialogFormField[] = [
  { key: 'name', label: '名称', required: true },
]

async function onFinish(values: DialogFormValues) {
  try {
    await fetch('/api/items', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(values),
    })
    UMessage.success('已保存')
    return true
  } catch {
    UMessage.error('网络异常')
    return false
  }
}
</script>

<template>
  <u-button type="primary" @click="visible = true">打开</u-button>
  <dialog-form
    v-model:visible="visible"
    title="新建"
    :fields="fields"
    :on-finish="onFinish"
  />
</template>

开发说明

实现位于 packages/components 仓库的 dialog-form；DrawerForm 在 src/drawer-form/index.ts 中复用同一实现。本地构建与文档站联调见开发指南。

ProDescriptions 高级描述列表

StatisticCard 统计卡片

DialogForm 对话框表单 ​

何时使用 ​

variant：对话框与抽屉 ​

显示与提交流程 ​

基础用法 ​

字段类型 ​

初始值与编辑 ​

提交失败时保持打开 ​

描述区：description 与插槽 ​

布局说明 ​

自定义表单项：#field-{key} 插槽 ​

自定义校验 ​

DialogForm 属性 ​

事件 ​

插槽 ​

footer 作用域参数 ​

DialogFormField ​

DialogFormValues ​

DialogFormFinishResult ​

DialogFormOnFinish ​

DrawerForm（可选） ​

DialogFormVariant ​

代码片段（最小示例） ​

开发说明 ​