Form 动态表单

基于 Element Plus el-form 的列配置驱动表单，通过 fields 数组声明式定义表单字段，支持自动生成校验规则、栅格布局、远程数据等功能。

基础用法

使用 fields 配置声明表单字段，v-model 双向绑定表单数据。

基础的 3 列栅格布局

姓名

手机号

所在地区

请选择地区

JSON

1

{...} // 3 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="3"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  name: "",
  phone: "",
  region: "",
})

const fields: FormField[] = [
  { prop: "name", label: "姓名", type: "input", placeholder: "请输入姓名" },
  { prop: "phone", label: "手机号", type: "input", placeholder: "请输入手机号" },
  { prop: "region", label: "所在地区", type: "select", placeholder: "请选择地区", options: [
    { label: "北京", value: "beijing" },
    { label: "上海", value: "shanghai" },
    { label: "广州", value: "guangzhou" },
  ]},
]
</script>

fields 完整示例

展示 fields 配置驱动表单的能力，覆盖所有常用字段类型：input、textarea、number、select、radio、checkbox、checkbox-btn、switch、cascader、date、daterange、datetime、datetimerange、time、timerange、transfer、upload，并演示 colSpan 栅格跨度控制。

fields 完整示例 — 涵盖所有字段类型

姓名

用户名

年龄

邮箱

个人简介

13 / 200

性别

男女

爱好

阅读旅行运动音乐

角色

状态

城市

工作模式

全职兼职外包

技能标签

VueReactTypeScriptNode.js

省市区

出生日期

在职时间段

-

上班打卡

下班打卡

上班时间

上班时间范围

所属部门

人员列表

技术部✓

产品部✓

设计部

市场部

运营部

人力资源部

已选中人员

清空

技术部

产品部

头像上传

支持 .jpg,.png,.gif 格式，最多 1 个文件

JSON

1

{...} // 21 items

<template>
  <hx-form
    ref="formRef"
    v-model="formData"
    :fields="fields"
    label-width="90px"
    :cols="2"
  >
    <template #action-buttons="{ validate, reset }">
      <div class="form-actions">
        <el-button type="primary" @click="handleSubmit">提交</el-button>
        <el-button @click="handleReset">重置</el-button>
      </div>
    </template>
  </hx-form>
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm , HxJsonView } from "@whhx/ui"
import type { FormField, FormExpose } from "@whhx/ui"
import { ElMessage } from "element-plus"
const formRef = ref<FormExpose>()

const formData = ref({
  name: "张三",
  username: "zhangsan",
  age: 25,
  email: "zhangsan@example.com",
  bio: "热爱编程，喜欢探索新技术。",
  gender: "male",
  hobbies: ["reading", "sports"],
  role: "editor",
  status: true,
  city: "beijing",
  workMode: "fulltime",
  skills: ["vue", "ts"],
  cityArea: ["shanghai", "pudong"],
  address: [],
  birthday: "1999-06-15",
  workPeriod: ["2023-01-01", "2025-06-01"],
  checkInTime: "2025-06-02 09:00:00",
  checkOutTime: "2025-06-02 18:00:00",
  workTimeRange: ["09:00:00", "18:00:00"],
  workTime: "09:00:00",
  department: ["tech", "product"],
  avatar: [],
  richContent: "",
})

const fields: FormField[] = [
  // ——— 基础信息 ———
  {
    prop: "name",
    label: "姓名",
    type: "input",
    placeholder: "请输入姓名",
    colSpan: 1,
    required: true,
  },
  {
    prop: "username",
    label: "用户名",
    type: "input",
    placeholder: "请输入用户名",
    colSpan: 1,
    required: true,
  },
  {
    prop: "age",
    label: "年龄",
    type: "number",
    placeholder: "请输入年龄",
    min: 18,
    max: 65,
    colSpan: 1,
  },
  {
    prop: "email",
    label: "邮箱",
    type: "input",
    placeholder: "请输入邮箱",
    colSpan: 1,
    required: true,
  },
  {
    prop: "bio",
    label: "个人简介",
    type: "textarea",
    placeholder: "请输入个人简介",
    rows: 2,
    maxlength: 200,
    showWordLimit: true,
    colSpan: 2,
  },

  // ——— 选择类组件 ———
  {
    prop: "gender",
    label: "性别",
    type: "radio",
    options: [
      { label: "男", value: "male" },
      { label: "女", value: "female" },
    ],
    colSpan: 1,
  },
  {
    prop: "hobbies",
    label: "爱好",
    type: "checkbox",
    options: [
      { label: "阅读", value: "reading" },
      { label: "旅行", value: "travel" },
      { label: "运动", value: "sports" },
      { label: "音乐", value: "music" },
    ],
    colSpan: 1,
  },
  {
    prop: "role",
    label: "角色",
    type: "select",
    placeholder: "请选择角色",
    options: [
      { label: "管理员", value: "admin" },
      { label: "编辑", value: "editor" },
      { label: "普通用户", value: "user" },
    ],
    colSpan: 1,
  },
  {
    prop: "status",
    label: "状态",
    type: "switch",
    colSpan: 1,
  },
  {
    prop: "city",
    label: "城市",
    type: "select",
    placeholder: "请选择城市",
    filterable: true,
    options: [
      { label: "北京", value: "beijing" },
      { label: "上海", value: "shanghai" },
      { label: "广州", value: "guangzhou" },
      { label: "深圳", value: "shenzhen" },
      { label: "杭州", value: "hangzhou" },
      { label: "成都", value: "chengdu" },
    ],
    colSpan: 2,
  },
  {
    prop: "workMode",
    label: "工作模式",
    type: "radio-btn",
    options: [
      { label: "全职", value: "fulltime" },
      { label: "兼职", value: "parttime" },
      { label: "外包", value: "outsourced" },
    ],
    colSpan: 1,
  },
  {
    prop: "skills",
    label: "技能标签",
    type: "checkbox-btn",
    options: [
      { label: "Vue", value: "vue" },
      { label: "React", value: "react" },
      { label: "TypeScript", value: "ts" },
      { label: "Node.js", value: "node" },
    ],
    colSpan: 2,
  },

  // ——— 级联选择 ———
  {
    prop: "cityArea",
    label: "省市区",
    type: "cascader",
    placeholder: "请选择省市区",
    filterable: true,
    options: [
      {
        label: "北京",
        value: "beijing",
        children: [
          { label: "朝阳区", value: "chaoyang" },
          { label: "海淀区", value: "haidian" },
        ],
      },
      {
        label: "上海",
        value: "shanghai",
        children: [
          { label: "浦东新区", value: "pudong" },
          { label: "徐汇区", value: "xuhui" },
        ],
      },
      {
        label: "广东",
        value: "guangdong",
        children: [
          { label: "广州", value: "guangzhou_city" },
          { label: "深圳", value: "shenzhen_city" },
        ],
      },
    ],
    colSpan: 2,
  },

  // ——— 日期时间 ———
  {
    prop: "birthday",
    label: "出生日期",
    type: "date",
    placeholder: "请选择出生日期",
    valueFormat: "YYYY-MM-DD",
    colSpan: 1,
  },
  {
    prop: "workPeriod",
    label: "在职时间段",
    type: "daterange",
    placeholder: "请选择在职时间段",
    valueFormat: "YYYY-MM-DD",
    colSpan: 1,
  },
  {
    prop: "checkInTime",
    label: "上班打卡",
    type: "datetime",
    placeholder: "请选择上班打卡时间",
    valueFormat: "YYYY-MM-DD HH:mm:ss",
    colSpan: 1,
  },
  {
    prop: "checkOutTime",
    label: "下班打卡",
    type: "datetime",
    placeholder: "请选择下班打卡时间",
    valueFormat: "YYYY-MM-DD HH:mm:ss",
    colSpan: 1,
  },
  {
    prop: "workTime",
    label: "上班时间",
    type: "time",
    placeholder: "请选择上班时间",
    valueFormat: "HH:mm:ss",
    colSpan: 1,
  },
  {
    prop: "workTimeRange",
    label: "上班时间范围",
    type: "timerange",
    placeholder: "请选择上班时间范围",
    valueFormat: "HH:mm:ss",
    colSpan: 2,
  },

  // ——— 穿梭框 ———
  {
    prop: "department",
    label: "所属部门",
    type: "transfer",
    placeholder: "请选择部门",
    options: [
      { label: "技术部", value: "tech" },
      { label: "产品部", value: "product" },
      { label: "设计部", value: "design" },
      { label: "市场部", value: "marketing" },
      { label: "运营部", value: "operations" },
      { label: "人力资源部", value: "hr" },
    ],
    colSpan: 2,
  },

  // ——— 上传 ———
  {
    prop: "avatar",
    label: "头像上传",
    type: "upload",
    accept: ".jpg,.png,.gif",
    limit: 1,
    listType: "picture-card",
    action: "/api/upload",
    headers: { Authorization: "Bearer token-xxx" },
    data: { category: "avatar" },
    name: "avatar",
    responseMapper: (res: any) => res["data"]["id"],
    previewUrl: "/api/upload/preview",
    placeholder: "上传头像",
    colSpan: 2,
  },
]

function handleSubmit() {
  formRef.value?.validate((valid) => {
    if (valid) {
      ElMessage.success("提交成功")
    }
  })
}

function handleReset() {
  formRef.value?.reset()
}
</script>

<style scoped>
.form-actions {
  display: flex;
  gap: 8px;
}
</style>

提交与重置

通过 ref 获取表单实例，调用 validate 校验和 reset 重置方法。默认操作区可通过 actions 插槽自定义。

自定义操作按钮

姓名

年龄

邮箱

JSON

1

{...} // 3 items

<template>
  <hx-form
    ref="formRef"
    v-model="formData"
    :fields="fields"
    :cols="2"
  >
    <template #action-buttons="{ validate, reset }">
      <div class="form-actions">
        <el-button type="primary" @click="handleSubmit">提交</el-button>
        <el-button @click="handleReset">重置</el-button>
      </div>
    </template>
  </hx-form>
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField, FormExpose } from "@whhx/ui"
import { ElMessage } from "element-plus"

const formRef = ref<FormExpose>()

const formData = ref({
  name: "",
  age: undefined,
  email: "",
})

const fields: FormField[] = [
  {
    prop: "name",
    label: "姓名",
    type: "input",
    placeholder: "请输入姓名",
    required: true,
    rules: [
      { min: 2, max: 10, message: "姓名长度在 2 到 10 个字符", trigger: "blur" }
    ]
  },
  {
    prop: "age",
    label: "年龄",
    type: "number",
    placeholder: "请输入年龄",
    required: true,
    rules: [
      { type: "number", min: 1, max: 150, message: "年龄必须在 1 到 150 之间", trigger: "change" }
    ]
  },
  { prop: "email", label: "邮箱", type: "input", placeholder: "请输入邮箱", required: true },
]

function handleSubmit() {
  formRef.value?.validate((valid) => {
    if (valid) {
      ElMessage.success("提交成功")
    }
  })
}

function handleReset() {
  formRef.value?.reset()
}
</script>

<style scoped>
.form-actions {
  display: flex;
  gap: 8px;
}
</style>

输入类型

支持 input、textarea、number 等文本输入类型。

文本输入 / 文本域 / 数字输入

文本输入

0 / 50

多行文本

0 / 200

数字输入

JSON

1

{...} // 3 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="2"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  input: "",
  textarea: "",
  number: undefined,
})

const fields: FormField[] = [
  { prop: "input", label: "文本输入", type: "input", placeholder: "请输入", maxlength: 50, showWordLimit: true },
  { prop: "textarea", label: "多行文本", type: "textarea", placeholder: "请输入描述内容", rows: 3, maxlength: 200, showWordLimit: true },
  { prop: "number", label: "数字输入", type: "number", placeholder: "请输入数字", min: 0, max: 100, step: 1 },
]
</script>

选择类组件

支持 select、radio、radio-btn、checkbox、switch 等选择类组件。

单选下拉 / 多选下拉 / 单选框 / 多选框 / 开关

单选下拉

请选择

多选下拉

请选择

单选按钮

是否

复选框组

唱歌跳舞编程

开关

JSON

1

{...} // 5 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="2"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  singleSelect: "",
  multiSelect: [],
  radio: "",
  checkbox: [],
  switch: false,
})

const fields: FormField[] = [
  { prop: "singleSelect", label: "单选下拉", type: "select", placeholder: "请选择", options: [
    { label: "选项一", value: "1" },
    { label: "选项二", value: "2" },
    { label: "选项三", value: "3" },
  ]},
  { prop: "multiSelect", label: "多选下拉", type: "select", multiple: true, placeholder: "请选择", options: [
    { label: "选项一", value: "1" },
    { label: "选项二", value: "2" },
    { label: "选项三", value: "3" },
  ]},
  { prop: "radio", label: "单选按钮", type: "radio", options: [
    { label: "是", value: "yes" },
    { label: "否", value: "no" },
  ]},
  { prop: "checkbox", label: "复选框组", type: "checkbox", options: [
    { label: "唱歌", value: "sing" },
    { label: "跳舞", value: "dance" },
    { label: "编程", value: "code" },
  ]},
  { prop: "switch", label: "开关", type: "switch" },
]
</script>

日期时间

支持 date、daterange、datetime、datetimerange、time、timerange 等日期时间类型。

日期 / 日期范围 / 日期时间 / 时间 / 时间范围

日期

日期范围

-

日期时间

日期时间范围

-

时间

时间范围

JSON

1

{...} // 6 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="2"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  date: "",
  dateRange: [],
  datetime: "",
  datetimerange: [],
  time: "",
  timeRange: [],
})

const fields: FormField[] = [
  { prop: "date", label: "日期", type: "date", placeholder: "请选择日期" },
  { prop: "dateRange", label: "日期范围", type: "daterange", placeholder: "请选择日期范围" },
  { prop: "datetime", label: "日期时间", type: "datetime", placeholder: "请选择日期时间" },
  { prop: "datetimerange", label: "日期时间范围", type: "datetimerange", placeholder: "请选择范围" },
  { prop: "time", label: "时间", type: "time", placeholder: "请选择时间" },
  { prop: "timeRange", label: "时间范围", type: "timerange", placeholder: "请选择时间范围" },
]
</script>

级联选择

cascader 类型支持多级联动，可通过 filterable 开启搜索功能。

级联选择器

城市选择

JSON

1

{...} // 1 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="2"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  cascader: "",
})

const fields: FormField[] = [
  { prop: "cascader", label: "城市选择", type: "cascader", placeholder: "请选择", filterable: true, options: [
    {
      label: "北京",
      value: "beijing",
      children: [
        { label: "朝阳区", value: "chaoyang" },
        { label: "海淀区", value: "haidian" },
      ]
    },
    {
      label: "上海",
      value: "shanghai",
      children: [
        { label: "浦东新区", value: "pudong" },
        { label: "徐汇区", value: "xuhui" },
      ]
    },
  ]},
]
</script>

远程数据

通过 remote 配置异步加载选项数据，支持 GET/POST 请求及响应字段映射；dependsOn 可实现省市区多级联动。

远程数据 / 民族 / 性别 / 省市联动

<template>
  <ClientOnly>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="2"
  />
  <hx-json-view :data="formData" />
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  gender: "",
  ethnicity: "",
  address: "",
})

const fields: FormField[] = [
  {
    prop: "gender",
    label: "性别",
    type: "radio",
    remote: {
      url: "/api/options/gender",
      labelKey: "label",
      valueKey: "value",
    },
  },
  {
    prop: "ethnicity",
    label: "民族",
    type: "select",
    placeholder: "请选择民族",
    filterable: true,
    remote: {
      url: "/api/options/ethnicity",
      labelKey: "label",
      valueKey: "value",
    },
  },
  {
    prop: "address",
    label: "湖北省市区",
    type: "cascader",
    placeholder: "请选择省市区",
    filterable: true,
    clearable: true,
    remote: {
      url: "/api/options/cascader",
      labelKey: "label",
      valueKey: "value",
      childrenKey: "children",
    },
  },
]
</script>

自动校验

通过 required: true 自动生成必填校验规则，rules 可添加自定义校验规则，两者自动合并。

required 自动校验 + rules 自定义校验

标题

类型

请选择类型

状态

启用禁用

JSON

1

{...} // 3 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="3"
  >
    <template #action-buttons="{ formData, validate }">
      <div class="form-actions">
        <el-button type="primary" @click="handleSearch(formData, validate)">搜索</el-button>
        <el-button>重置</el-button>
      </div>
    </template>
  </hx-form>
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"
import { ElMessage } from "element-plus"

const formData = ref({
  title: "",
  type: "",
  status: "",
})

const fields: FormField[] = [
  { prop: "title", label: "标题", type: "input", placeholder: "请输入标题", required: true },
  { prop: "type", label: "类型", type: "select", placeholder: "请选择类型", required: true, options: [
    { label: "文章", value: "article" },
    { label: "视频", value: "video" },
    { label: "图片", value: "image" },
  ]},
  { prop: "status", label: "状态", type: "radio", options: [
    { label: "启用", value: "enabled" },
    { label: "禁用", value: "disabled" },
  ]},
]

function handleSearch(data: Record<string, any>, validate: any) {
  validate(valid => {
    if (valid) {
      ElMessage.success("搜索参数: " + JSON.stringify(data))
    }
  })
}
</script>

<style scoped>
.form-actions {
  display: flex;
  gap: 8px;
}
</style>

上传组件

type: 'upload' 支持 headers、data、name、withCredentials 等 el-upload 原生参数透传，通过 responseMapper 提取上传后的文件 ID，通过 previewUrl 配置文件预览接口。

表单中使用 upload 组件

姓名

头像

支持 .jpg,.png,.gif 格式，最多 1 个文件

附件

支持 .jpg,.png,.pdf,.doc,.docx 格式，最多 5 个文件

JSON

1

{...} // 3 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :inline="false"
    :cols="3"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  name: "",
  avatar: [],
  attachments: [],
})

const fields: FormField[] = [
  { prop: "name", label: "姓名", type: "input", placeholder: "请输入姓名" },
  {
    prop: "avatar",
    label: "头像",
    type: "upload",
    accept: ".jpg,.png,.gif",
    limit: 1,
    listType: "picture-card",
    action: "/api/upload",
    headers: { Authorization: "Bearer token-xxx" },
    data: { category: "avatar" },
    name: "avatar",
    responseMapper: (res: any) => res["data"]["id"],
    previewUrl: "/api/upload/preview",
    placeholder: "上传头像",
  },
  {
    prop: "attachments",
    label: "附件",
    type: "upload",
    accept: ".jpg,.png,.pdf,.doc,.docx",
    limit: 5,
    multiple: true,
    action: "/api/upload",
    headers: { Authorization: "Bearer token-xxx" },
    data: { category: "attachment" },
    responseMapper: (res: any) => res["data"]["id"],
    previewUrl: "/api/upload/preview",
    placeholder: "上传附件",
  },
]
</script>

全局配置

可通过 HxConfigProvider 在应用顶层统一配置 Form 组件的默认值：

<HxConfigProvider :form="{ cols: 4, gap: 12 }">
  <!-- 全局生效 -->
</HxConfigProvider>

配置优先级：Props > ConfigProvider > 默认值，即 Props 传入的值会覆盖全局配置。

通过 ConfigProvider 全局配置 Form 布局

姓名

手机号

所在地区

请选择所在地区

状态

请选择状态

类型

JSON

1

{...} // 5 items

<template>
  <hx-form
    v-model="formData"
    :fields="fields"
    :cols="4"
  />
  <hx-json-view :data="formData" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxForm as Form, HxJsonView } from "@whhx/ui"
import type { FormField } from "@whhx/ui"

const formData = ref({
  name: "",
  phone: "",
  region: "",
  status: "",
  type: "",
})

const fields: FormField[] = [
  { prop: "name", label: "姓名", type: "input", placeholder: "请输入姓名" },
  { prop: "phone", label: "手机号", type: "input", placeholder: "请输入手机号" },
  { prop: "region", label: "所在地区", type: "select", options: [
    { label: "北京", value: "beijing" },
    { label: "上海", value: "shanghai" },
    { label: "广州", value: "guangzhou" },
  ]},
  { prop: "status", label: "状态", type: "select", options: [
    { label: "启用", value: "1" },
    { label: "禁用", value: "0" },
  ]},
  { prop: "type", label: "类型", type: "input", placeholder: "请输入类型" },
]
</script>

API

Props

参数	说明	类型	默认值
v-model / modelValue	表单数据对象	Record<string, any>	{}
fields	表单字段配置数组	FormField[]	-
cols	栅格列数	number	3
gap	栅格间距（px）	number	16
minColWidth	栅格最小列宽（px）	number	0
showAction	是否显示操作按钮区域	boolean	true
labelWidth	表单级别 label 宽度	string | number	-
labelPosition	表单级别 label 位置	'left' | 'right' | 'top'	'right'

FormField 类型

通用属性

属性	说明	类型
prop	字段名	string
label	标签文本	string
type	字段类型	FieldType
defaultValue	默认值	any
colSpan	栅格列跨度	number
placeholder	占位文本	string
clearable	是否可清空	boolean
disabled	是否禁用	boolean
hidden	是否隐藏	boolean
required	是否必填（自动生成校验）	boolean
labelWidth	字段级别 label 宽度（优先级高于表单级别）	string | number
labelPosition	字段级别 label 位置	'left' | 'right' | 'top'

文本输入类（input / textarea）

属性	说明	类型
maxlength	最大输入长度	number
showWordLimit	是否显示字数统计	boolean
rows	文本域行数（textarea）	number
prefixIcon	输入框前缀图标类名	string
suffixIcon	输入框后缀图标类名	string
autocomplete	自动补全	string

数字输入类（number）

属性	说明	类型
min	最小值	number
max	最大值	number
step	步进值	number
precision	精度（小数位数）	number
stepStrictly	是否强制输入值为 step 的倍数	boolean

选择类组件（select）

属性	说明	类型
options	选项数据	OptionItem[] | GroupOptionItem[]
remote	远程数据配置	RemoteConfig
multiple	是否多选	boolean
filterable	是否可搜索	boolean
collapseTags	多选时是否折叠 Tag	boolean
collapseTagsTooltip	多选时是否展示 Tag 的 tooltip	boolean
modelValueType	值类型：'string' 逗号拼接，'array' 数组	'string' | 'array'

单选/多选类（radio / checkbox）

属性	说明	类型
options	选项数据	OptionItem[]
remote	远程数据配置	RemoteConfig
variant	按钮形态：radio-btn / checkbox-btn	'radio' | 'radio-btn' / 'checkbox' | 'checkbox-btn'
modelValueType	值类型	'string' | 'array'

日期时间类（date / daterange / datetime / datetimerange / time / timerange）

属性	说明	类型
valueFormat	值格式化字符串	string
format	显示格式化字符串	string
disableFutureTime	是否禁用未来时间（datetime）	boolean
disabledDate	禁用日期函数	(date: Date) => boolean
disabledTime	禁用时间函数（time / timerange）	() => { hours?: number[]; minutes?: number[]; seconds?: number[] }

上传类（upload）

属性	说明	类型
action	上传地址	string
accept	接受的文件类型	string
limit	最大上传数量	number
headers	请求头	Record<string, string>
data	附带的表单数据	Record<string, string | Blob>
name	上传的文件字段名	string
withCredentials	携带 cookie	boolean
listType	列表展示类型	'text' | 'picture' | 'picture-card' | 'file-preview'
autoUpload	是否自动上传	boolean
valueMapper	上传文件值映射函数	(file: any) => any
responseMapper	上传响应值映射函数	(response: any, file: any) => any
previewUrl	文件预览接口地址	string
deleteUrl	文件删除接口地址	string
showDownload	是否显示下载按钮	boolean
fileRender	自定义上传文件列表项渲染	(file: any, actions: { remove }) => VNode
filePreviewRender	自定义上传文件预览渲染	(file: any, actions: { remove }) => VNode

其他属性

属性	说明	类型
cascaderProps	级联选择面板配置（cascader）	CascaderPanelProps
rules	自定义校验规则	any[]
componentProps	透传给底层组件的属性	Record<string, any>
formItemProps	透传给 el-form-item 的属性	Record<string, any>
onChange	值变更回调	(value: any, formData: Record<string, any>) => void
richEditorParams	富文本编辑器配置（richeditor）	RichEditorParams
render	自定义渲染函数（type='render'）	(formData, field) => VNode

FieldType 可选值

input | textarea | number | select | radio | radio-btn | checkbox |
checkbox-btn | switch | cascader | datetime | datetimerange | date |
daterange | time | timerange | upload | richeditor | slot | render

FormExpose

通过 ref 获取的方法：

方法	说明	返回值
validate	校验表单，可传入回调函数	Promise<boolean>
reset	重置表单	void
getFormData	获取表单数据	Record<string, any>
setFormData	设置表单数据（用于回填）	(data: Partial<Record<string, any>>) => void
getElFormRef	获取 el-form 实例	any

Slots

插槽名	说明	作用域变量
default	默认插槽，渲染自定义表单项	-
[prop]	渲染指定字段的表单项	{ formData, field }
action-buttons	操作按钮区域（showAction=false 时不显示）	{ formData, validate, reset }
search	查询按钮区域（位于操作按钮左侧）	{ formData, validate, reset }