CrudForm 共用表单
新增、编辑、查看共用一份 fields,通过 mode 配置标题、只读和校验差异。在 CrudPage 中传入 formConfig 即可自动联动,以下示例用于独立使用。
基础用法
vue
<template>
<CrudForm ref="formRef" :form-config="formConfig" @saved="refresh" />
</template>typescript
const formConfig: CrudFormConfig<UserForm> = {
title: ({ mode }) => ({ create: "新增用户", edit: "编辑用户", view: "查看用户" })[mode],
fields: [
{ prop: "username", label: "用户名", type: "input", required: true },
{ prop: "nickname", label: "昵称", type: "input", required: true },
],
submitForm(data, { mode, id }) {
if (mode === "create") return UserAPI.create(data);
if (id === undefined) throw new Error("缺少用户 ID");
return UserAPI.update(String(id), data);
},
};
// 打开新增
formRef.value?.openForm("create");
// 打开编辑并加载详情
formRef.value?.openForm("edit", row);
await formRef.value?.loadFormData(() => UserAPI.getFormData(String(row.id)));按模式配置字段
label、visible、readonly、required 支持条件函数,接收 { mode, id, model }:
typescript
{
fields: [
{
prop: "username",
label: ({ mode }) => (mode === "create" ? "用户名" : "登录账号"),
type: "input",
required: true,
readonly: ({ mode }) => mode === "edit",
},
{
prop: "remark",
label: "变更说明",
type: "input",
visible: ({ mode }) => mode !== "view",
required: ({ mode }) => mode === "edit",
attrs: { type: "textarea", rows: 3 },
},
],
}- 条件函数保持同步,不发请求、不修改模型
required只覆盖必填标志,保留rules中的其他约束- 隐藏字段不参与校验,但模型值仍会提交;需要排除时在
beforeSubmit中删除 - 查看模式自动禁用全部字段
保留未展示的字段
详情仅回填 fields 中声明的字段。更新接口需要但不展示的数据,声明为 hidden: true。
提交与失败处理
typescript
{
beforeSubmit(data) {
data.username = data.username?.trim();
},
submitForm(data, { mode, id }) {
if (mode === "create") return UserAPI.create(data);
if (id === undefined) throw new Error("缺少用户 ID");
return UserAPI.update(String(id), data);
},
}submitForm必须返回 Promise;beforeSubmit处理提交副本,可异步- 校验或提交期间禁用表单,防止重复提交;失败保留输入和错误
- 成功提示后关闭表单并触发
saved;successMessage: false关闭提示 - 每次打开重建初值;详情加载后重置恢复本次详情
- 编辑、查看的提交目标使用打开时的主键,不受详情响应中的 id 影响
自定义控件
字段配置 type: "custom",通过插槽渲染业务控件:
typescript
{ prop: "gender", label: "性别", type: "custom", initialValue: 1 }vue
<CrudForm ref="formRef" :form-config="formConfig" @saved="refresh">
<template #gender="{ formData, prop, attrs }">
<DictSelect v-model="formData[prop]" code="gender" v-bind="attrs" />
</template>
<template #bottom="{ formData }">
<p v-if="formData.remark">{{ formData.remark }}</p>
</template>
</CrudForm>自定义控件需绑定 attrs,以应用查看、加载和保存期间的禁用状态。普通控件可用 slotName 转发同名原生插槽(如 input 的 append)。
抽屉模式
typescript
{
component: "drawer",
drawer: { size: 560 },
}dialog、drawer 配置容器,form 配置 Element Plus Form 属性,字段原生属性放 attrs、事件放 events。
API
Attributes
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| form-config | 表单配置 | CrudFormConfig | — |
FormConfig
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| fields | 共用字段数组 | CrudFormField[] | — |
| title | 标题,支持模式条件函数 | string | (ctx) => string | — |
| rowKey | 主键名 | string | id |
| component | 容器类型 | 'dialog' | 'drawer' | dialog |
| dialog / drawer | 容器原生属性 | DialogProps / DrawerProps | — |
| form | Element Plus Form 属性 | FormProps | — |
| beforeSubmit | 提交前处理副本 | (data) => void | Promise | — |
| submitForm | 保存请求,查看模式不调用 | (data, ctx) => Promise | — |
| successMessage | 成功提示,false 不提示 | string | false | 保存成功 |
| colon | 标签末尾添加冒号 | boolean | false |
上下文 ctx 为 { mode, id, model },mode 为 create / edit / view。
CrudFormField
继承 CrudField 全部属性,label 支持条件函数,额外属性:
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| visible | 是否渲染并参与校验 | boolean | (ctx) => boolean | true |
| readonly | input 只读,其他控件禁用 | boolean | (ctx) => boolean | false |
| required | 动态必填 | boolean | (ctx) => boolean | — |
表单控件类型:搜索全部类型,另支持 text(只读文本)、radio、checkbox、switch、icon-select。select / radio / checkbox 的 options 支持数组或 Ref。
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| saved | 保存成功,表单已关闭 | — |
Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
| {prop} 或 | custom 字段的控件 | { prop, label, mode, formData, attrs } |
| label- | 字段标签 | 同上 |
| bottom | 全部字段之后 | 同上 |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| openForm | 按模式打开,edit/view 需带主键的行 | (mode?, row?) => boolean |
| closeForm | 关闭,保存中不关闭 | () => void |
| loadFormData | 加载详情,隔离旧响应 | (loader) => Promise<void> |
| setFormData | 回填并更新重置目标 | (data) => void |
| getFormData | 读取模型引用或指定字段 | (key?) => CrudRecord | unknown |
| setFieldValue | 修改一个字段 | (key, value) => void |
