FY Dynamic Form

一个基于 Vue 3 + Element Plus 的强大动态表单组件库，支持表单字段的动态渲染、动态数据源、字段关联、事件处理等高级功能。

✨ 特性

• 🚀 动态渲染: 基于 JSON 配置动态生成表单
• 🎯 事件系统: 灵活的事件处理机制，支持沙盒环境执行
• 📡 异步数据: 支持动态获取选项数据和表单效果
• 🎨 丰富组件: 内置 25+ 组件，支持注册自定义组件
• 🎭 条件渲染: 支持基于表达式的字段显示/隐藏/禁用
• 🔄 数据联动: 支持字段间的数据联动和计算属性
• 🎨 主题适配: 支持明暗主题切换

📦 安装

npm install fy-dynamic-form

# 你还需要自行安装必要依赖
npm install axios
npm install element-plus

# 如果你需要使用富文本组件
npm install @wangeditor-next/editor-for-vue

🚀 快速开始

基础用法

<template>
  <FyDynamicForm
    :config="formConfig"
    :init-data="initialData"
    ref="formRef"
  />
</template>

<script setup lang="ts">
import { FyDynamicForm } from 'fy-dynamic-form'
import type { FyFormConfig } from 'fy-dynamic-form'

const formRef = ref()

// 初始数据
const initialData = {
  username: 'admin'
}

const formConfig: FyFormConfig = {
  form: {
    labelWidth: '100px',
    labelPosition: 'top',
    size: 'default'
  },
  properties: [
    {
      type: 'input',
      field: 'username',
      label: '用户名',
      required: true,
      props: {
        placeholder: '请输入用户名'
      }
    }
}
</script>

获取表单数据

// 验证表单
const isValid = await formRef.value.validate()

// 获取表单数据
const formData = formRef.value.getValues()

// 重置表单
formRef.value.resetFields()

🎨 内置组件

| 组件类型 | 说明 | |--------------|--------------| | input | 输入框 | | number | 数字输入框 | | select | 选择器 | | password | 密码输入框 | | textarea | 文本域 | | checkbox | 复选框组 | | radio | 单选框组 | | date | 日期选择器 | | dateRange | 日期范围选择器 | | dateTime | 日期时间选择器 | | dateTimeRange | 日期时间范围选择器 | | inputTag | 标签输入框 | | divider | 分割线 | | image | 图片展示 | | rate | 评分组件 | | slider | 滑块 | | switch | 开关 | | color | 颜色选择器 | | mention | 提及 | | upload | 上传 | | richText | 富文本 | | html | HTML |

🔧 配置说明

FyFormConfig 接口

interface FyFormConfig {
  form: FyFormProps           // 表单配置
  title?: string              // 表单标题
  description?: string        // 表单描述
  watermark?: FyFormWatermark // 水印配置
  properties: FyFormProperties[] // 字段配置数组
}

FyFormProps 接口

interface FyFormProps {
  inline?: boolean                    // 是否行内表单
  labelWidth?: string                 // 标签宽度
  labelPosition?: 'top' | 'left' | 'right' // 标签位置
  hideRequiredAsterisk?: boolean      // 是否隐藏必填星号
  size?: '' | 'large' | 'default' | 'small' // 表单尺寸
  showMessage?: boolean               // 是否显示验证消息
  messages?: {                        // 自定义验证消息
    required?: string
  }
}

FyFormProperties 接口

interface FyFormProperties {
  type: string                        // 组件类型
  label: string                       // 字段标签
  field?: string                      // 字段名
  required?: boolean                  // 是否必填
  options?: any[]                     // 选项数据
  rule?: any[]                        // 验证规则
  props?: Record<string, any>         // 组件属性
  hide?: boolean                      // 是否隐藏
  effect?: FyEffect                   // 动态效果配置
  computeds?: FyComputed[]            // 计算属性配置
  events?: Record<string, string | ((event: any) => void)> // 事件处理
}

🔗 高级功能

1. 动态数据源 (Effect)

const formConfig = {
  properties: [
    {
      type: 'select',
      field: 'city',
      label: '城市',
      options: [],
      effect: {
        fetch: {
          action: "https://api.example.com/cities",
          method: "GET",
          headers: {
            "Authorization": "Bearer token"
          },
          data: { 
            province: "{{province}}" // 动态参数，引用其他字段值
          },
          to: "options" // 将返回数据设置到options(从res.data.data)返回
        }
      }
    }
  ]
}

Effect 配置说明：

• action: 请求地址
• method: 请求方法 (GET, POST, PUT, DELETE)
• headers: 请求头
• data: 请求体数据
• query: 查询参数
• to: 数据目标位置 (options, props, rule, label)

2. 字段联动 (Computed)

const formConfig = {
  properties: [
    {
      type: 'number',
      field: 'age',
      label: '年龄',
      computeds: [
        {
          type: 'required',
          condition: 'userType === "student"' // 当用户类型为学生时必填
        },
        {
          type: 'hide',
          condition: 'age < 18' // 年龄小于18时隐藏
        },
        {
          type: 'disable',
          condition: 'isLocked' // 当锁定状态时禁用
        }
      ]
    }
  ]
}

Computed 类型：

• required: 动态设置必填状态
• hide: 动态显示/隐藏字段
• disable: 动态启用/禁用字段

条件表达式： 使用 expr-eval 库支持的表达式语法，可以引用表单中的其他字段值。

3. 事件处理 (Events)

const formConfig = {
  properties: [
    {
      type: 'select',
      field: 'userType',
      label: '用户类型',
      events: {
        change: 'handleEffectByField("userType")',
        focus: 'console.log("获得焦点")',
        blur: 'console.log("失去焦点")'
      }
    }
  ]
}

事件处理说明：

• 支持所有 Element Plus 组件的事件
• 事件处理函数在沙盒环境中执行
• 全局变量：event（事件）、formModel（响应式）、formConfig（非响应式）、handleEffectByField（行为执行函数）

4. 自定义组件注册

import { useComponent } from 'fy-dynamic-form'
import MyCustomComponent from './MyCustomComponent.vue'

// 注册自定义组件
useComponent.registerComponent('myCustom', MyCustomComponent)

// 在配置中使用
const formConfig = {
  properties: [
    {
      type: 'myCustom',
      field: 'customField',
      label: '自定义组件',
      props: {
        // 自定义属性
      }
    }
  ]
}

🎯 API 参考

Props

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | FyFormConfig | - | 表单配置对象 | | initData | Record<string, any> | - | 初始数据 |

Methods

| 方法名 | 参数 | 返回值 | 说明 | |--------|------|--------|------| | validate | - | Promise | 验证表单 | | resetFields | - | void | 重置表单字段 | | getValues | - | Record<string, any> | 获取表单数据 |

🎨 主题适配

暗色主题

/* 引入暗色主题变量 */
@import 'fy-dynamic-form/dark-vars.css';

/* 或者自定义暗色主题 */
:root {
  --el-color-primary: #409eff;
  --el-bg-color: #1a1a1a;
  --el-text-color-primary: #ffffff;
  /* 更多主题变量... */
}

📋 完整示例

用户注册表单

const userFormConfig = {
  form: {
    labelWidth: '120px',
    labelPosition: 'left',
    size: 'default'
  },
  properties: [
    {
      type: 'input',
      field: 'username',
      label: '用户名',
      required: true,
      props: {
        placeholder: '请输入用户名',
        maxlength: 20
      },
      rule: [
        { required: true, message: '请输入用户名', trigger: 'blur' },
        { min: 3, max: 20, message: '长度在 3 到 20 个字符', trigger: 'blur' }
      ]
    },
    {
      type: 'password',
      field: 'password',
      label: '密码',
      required: true,
      props: {
        placeholder: '请输入密码',
        showPassword: true
      }
    },
    {
      type: 'select',
      field: 'userType',
      label: '用户类型',
      required: true,
      options: [
        { label: '普通用户', value: 'user' },
        { label: '管理员', value: 'admin' },
        { label: 'VIP用户', value: 'vip' }
      ],
      events: {
        change: 'console.log("用户类型改变为:", formModel.userType)'
      }
    },
    {
      type: 'date',
      field: 'birthday',
      label: '生日',
      props: {
        type: 'date',
        placeholder: '选择日期'
      }
    },
    {
      type: 'textarea',
      field: 'description',
      label: '个人简介',
      props: {
        rows: 4,
        placeholder: '请输入个人简介'
      }
    }
  ]
}

📄 许可证

MIT License

FY Dynamic Form - 让表单开发更简单、更高效！ 🚀