Skip to content

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主键名stringid
component容器类型'dialog' | 'drawer'dialog
dialog / drawer容器原生属性DialogProps / DrawerProps—
formElement Plus Form 属性FormProps—
beforeSubmit提交前处理副本(data) => void | Promise—
submitForm保存请求,查看模式不调用(data, ctx) => Promise—
successMessage成功提示,false 不提示string | false保存成功
colon标签末尾添加冒号booleanfalse

上下文 ctx 为 { mode, id, model },mode 为 create / edit / view。

CrudFormField ​

继承 CrudField 全部属性,label 支持条件函数,额外属性:

属性说明类型默认值
visible是否渲染并参与校验boolean | (ctx) => booleantrue
readonlyinput 只读,其他控件禁用boolean | (ctx) => booleanfalse
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

基于 MIT 许可发布 · 如需部署协助或二开定制,请查看 支持与合作