element-plus-dynamic-form-test

Element Plus 动态表单

一个基于 Element Plus 的强大动态表单组件库，支持拖拽式表单构建器和丰富的字段类型。

特性

• 🚀 开箱即用 - 基于 Element Plus，无需额外配置
• 🎨 可视化构建 - 提供拖拽式表单构建器
• 📝 丰富字段 - 支持输入框、选择器、日期、上传等多种字段类型
• ✅ 强大验证 - 内置验证规则，支持自定义验证
• 🔧 高度可配置 - 灵活的字段配置和表单属性
• 📱 响应式设计 - 适配各种屏幕尺寸
• 🎯 TypeScript - 完整的类型定义支持

安装

npm install element-plus-dynamic-form

快速开始

基础用法

<template>
  <DynamicForm :config="formConfig" @submit="handleSubmit" @field-change="handleFieldChange" />
</template>

<script setup>
import { DynamicForm } from 'element-plus-dynamic-form'
import { builtinRules } from 'element-plus-dynamic-form'

const formConfig = {
  fields: [
    {
      prop: 'name',
      label: '姓名',
      type: 'input',
      placeholder: '请输入姓名',
      required: true,
      rules: [builtinRules.required('请输入姓名')]
    },
    {
      prop: 'email',
      label: '邮箱',
      type: 'input',
      placeholder: '请输入邮箱',
      required: true,
      rules: [builtinRules.required('请输入邮箱'), builtinRules.email('请输入有效的邮箱地址')]
    }
  ],
  onSubmit: async (formData) => {
    console.log('表单数据:', formData)
  }
}

const handleSubmit = (formData) => {
  console.log('提交数据:', formData)
}

const handleFieldChange = (prop, value, formData) => {
  console.log('字段变化:', prop, value)
}
</script>

使用表单构建器

<template>
  <FormBuilder />
</template>

<script setup>
import { FormBuilder } from 'element-plus-dynamic-form'
</script>

字段类型

输入框 (input)

{
  prop: 'username',
  label: '用户名',
  type: 'input',
  placeholder: '请输入用户名',
  maxlength: 20,
  minlength: 3,
  showWordLimit: true,
  clearable: true
}

文本域 (textarea)

{
  prop: 'description',
  label: '描述',
  type: 'textarea',
  placeholder: '请输入描述',
  rows: 4,
  maxlength: 200,
  showWordLimit: true,
  resize: 'vertical'
}

选择器 (select)

{
  prop: 'category',
  label: '分类',
  type: 'select',
  placeholder: '请选择分类',
  options: [
    { label: '选项1', value: 'option1' },
    { label: '选项2', value: 'option2' }
  ],
  clearable: true,
  filterable: true,
  multiple: false
}

单选框 (radio)

{
  prop: 'gender',
  label: '性别',
  type: 'radio',
  options: [
    { label: '男', value: 'male' },
    { label: '女', value: 'female' }
  ],
  border: true
}

复选框 (checkbox)

{
  prop: 'hobbies',
  label: '兴趣爱好',
  type: 'checkbox',
  options: [
    { label: '读书', value: 'reading' },
    { label: '运动', value: 'sports' }
  ],
  min: 1,
  max: 3
}

日期选择器 (date)

{
  prop: 'birthday',
  label: '生日',
  type: 'date',
  placeholder: '请选择生日',
  format: 'YYYY-MM-DD',
  valueFormat: 'YYYY-MM-DD',
  clearable: true
}

数字输入框 (number)

{
  prop: 'age',
  label: '年龄',
  type: 'number',
  placeholder: '请输入年龄',
  min: 0,
  max: 120,
  step: 1,
  controls: true
}

开关 (switch)

{
  prop: 'enabled',
  label: '启用',
  type: 'switch',
  activeValue: true,
  inactiveValue: false,
  activeText: '启用',
  inactiveText: '禁用'
}

滑块 (slider)

{
  prop: 'score',
  label: '评分',
  type: 'slider',
  min: 0,
  max: 100,
  step: 1,
  showInput: true,
  showTooltip: true
}

文件上传 (upload)

{
  prop: 'avatar',
  label: '头像',
  type: 'upload',
  action: '/api/upload',
  accept: 'image/*',
  maxSize: 5,
  maxCount: 1,
  drag: true
}

验证规则

内置验证规则

import { builtinRules } from 'element-plus-dynamic-form'

// 必填
builtinRules.required('此字段是必填项')

// 邮箱
builtinRules.email('请输入有效的邮箱地址')

// 手机号
builtinRules.phone('请输入有效的手机号')

// URL
builtinRules.url('请输入有效的URL')

// 数字
builtinRules.number('请输入有效的数字')

// 整数
builtinRules.integer('请输入整数')

// 长度限制
builtinRules.minLength(3, '最少3个字符')
builtinRules.maxLength(20, '最多20个字符')

// 数值范围
builtinRules.min(0, '不能小于0')
builtinRules.max(100, '不能大于100')

// 自定义验证
builtinRules.custom((value, formData) => {
  // 返回 true 表示验证通过
  // 返回 false 或字符串表示验证失败
  return value.length >= 6
}, '密码至少6位')

自定义验证规则

{
  prop: 'password',
  label: '密码',
  type: 'input',
  rules: [
    {
      required: true,
      message: '请输入密码'
    },
    {
      validator: (rule, value, formData) => {
        if (value.length < 6) {
          return new Error('密码至少6位')
        }
        return true
      }
    }
  ]
}

API 参考

DynamicForm Props

参数	说明	类型	默认值
config	表单配置	DynamicFormConfig	-
showSubmitButton	是否显示提交按钮	boolean	true
showResetButton	是否显示重置按钮	boolean	true
submitButtonText	提交按钮文本	string	'提交'
resetButtonText	重置按钮文本	string	'重置'
modelValue	表单数据	Record<string, any>	{}

DynamicForm Events

事件名	说明	参数
submit	表单提交	(formData: Record<string, any>)
reset	表单重置	()
field-change	字段值变化	(prop: string, value: any, formData: Record<string, any>)
update:modelValue	表单数据更新	(formData: Record<string, any>)

DynamicForm Methods

方法名	说明	参数	返回值
getFormData	获取表单数据	-	Record<string, any>
setFormData	设置表单数据	(data: Record<string, any>)	void
validate	验证表单	-	Promise
validateField	验证指定字段	(prop: string)	Promise
resetForm	重置表单	-	void
clearValidate	清除验证	(props?: string[])	void
submit	提交表单	-	Promise

FieldConfig

参数	说明	类型	默认值
prop	字段唯一标识	string	-
label	字段标签	string	-
type	字段类型	FieldType	-
value	字段值	any	-
required	是否必填	boolean	false
disabled	是否禁用	boolean	false
readonly	是否只读	boolean	false
placeholder	占位符	string	-
help	帮助文本	string	-
width	字段宽度	string | number	-
visible	是否显示	boolean	true
className	自定义样式类	string	-
rules	验证规则	FormRules[string]	-
dependencies	字段依赖	string[]	-

高级用法

字段依赖

{
  prop: 'country',
  label: '国家',
  type: 'select',
  options: [
    { label: '中国', value: 'china' },
    { label: '美国', value: 'usa' }
  ]
},
{
  prop: 'city',
  label: '城市',
  type: 'select',
  dependencies: ['country'], // 依赖country字段
  options: [] // 根据country动态设置
}

自定义组件

{
  prop: 'custom',
  label: '自定义字段',
  type: 'custom',
  component: MyCustomComponent,
  componentProps: {
    // 传递给自定义组件的属性
  }
}

表单构建器

表单构建器提供了可视化的表单设计界面：

• 拖拽字段类型到设计区域
• 实时预览表单效果
• 配置字段属性
• 导出表单配置
• 生成代码

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查
npm run type-check

# 代码检查
npm run lint

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 支持基础字段类型
• 提供表单构建器
• 完整的 TypeScript 支持