xsj-form3

Vue 3 表单设计器和渲染器，支持可视化拖拽设计表单，包含自定义 PersonTree 人员选择组件

特性

• 🎨 可视化拖拽式表单设计
• 📱 支持 PC、Pad、H5 三种布局
• 🔧 支持自定义组件（包含 PersonTree 人员选择组件）
• 🎯 运行时动态加载表单
• 💅 支持自定义 CSS 样式
• ✅ 支持自定义校验逻辑
• 🌍 支持国际化多语言
• 📦 可导出 Vue 组件、HTML 源码
• 🚀 基于 Vue 3 + Element Plus

安装

npm install xsj-form3
# 或
pnpm add xsj-form3
# 或
yarn add xsj-form3

必需依赖：

npm install vue@^3.2.32 element-plus@^2.2.22

快速开始

1. 配置 Vite（重要！）

在使用 xsj-form3 的项目中，修改 vite.config.js：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  
  optimizeDeps: {
    // 排除 xsj-form3，避免预构建错误
    exclude: ['xsj-form3']
  }
})

2. 引入依赖

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// 引入 Element Plus
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

// 引入 xsj-form3
import VFormDesigner from 'xsj-form3'
import 'xsj-form3/style'

const app = createApp(App)
app.use(ElementPlus)
app.use(VFormDesigner)
app.mount('#app')

3. 使用表单设计器

<template>
  <VFormDesigner ref="vfDesignerRef" />
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const vfDesignerRef = ref(null)
    
    // 获取表单 JSON
    const getFormJson = () => {
      return vfDesignerRef.value?.getFormJson()
    }
    
    return { vfDesignerRef, getFormJson }
  }
}
</script>

4. 使用表单渲染器

<template>
  <VFormRender 
    :form-json="formJson"
    :form-data="formData"
  />
</template>

<script>
import { ref } from 'vue'
import VFormRender from 'xsj-form3/render'
import 'xsj-form3/render/style'

export default {
  components: { VFormRender },
  setup() {
    const formJson = ref({
      formConfig: {
        labelWidth: 100,
        labelPosition: 'left'
      },
      widgetList: []
    })
    
    const formData = ref({})
    
    return { formJson, formData }
  }
}
</script>

自定义组件

PersonTree 人员选择组件

本包包含自定义的 PersonTree 人员选择组件，可以在表单设计器的"自定义扩展字段"分类中找到。

使用示例

在表单设计器中：

1. 从左侧组件面板的"自定义扩展字段"分类中找到"人员选择"组件
2. 拖拽到表单设计区域
3. 在右侧属性面板中配置组件属性

onChange 事件示例

// onChange 事件代码
if (value && value.length > 0) {
  const personId = value[0].joinUserId || value[0].id
  
  // 调用远程接口获取人员详细信息
  window.axios.get('/api/person/detail', {
    params: { id: personId }
  }).then(res => {
    if (res.data && res.data.code === 200) {
      const personInfo = res.data.data
      
      // 更新其他表单字段
      const nameField = this.getWidgetRef('personName')
      if (nameField) {
        nameField.setValue(personInfo.name)
      }
    }
  })
}

API

VFormDesigner

表单设计器组件

Props

• globalDsv (Object): 全局数据源变量

Methods

• getFormJson(): 获取表单 JSON 配置
• setFormJson(json): 设置表单 JSON 配置

VFormRender

表单渲染器组件

Props

• formJson (Object): 表单 JSON 配置
• formData (Object): 表单数据
• optionData (Object): 选项数据
• globalDsv (Object): 全局数据源变量

Methods

• getFormData(needValidation): 获取表单数据
• setFormData(formData): 设置表单数据
• validateForm(callback): 校验表单
• resetForm(): 重置表单

依赖要求

• Vue 3.2.32+
• Element Plus 2.2.22+

浏览器支持

• Chrome（及同内核浏览器）
• Firefox
• Safari

常见问题

Vite 504 错误

如果遇到 504 (Outdated Optimize Dep) 错误，在 vite.config.js 中添加：

optimizeDeps: {
  exclude: ['xsj-form3']
}

然后清除缓存：

rm -rf node_modules/.vite
npm run dev

详细解决方案请查看 VITE_USAGE_FIX.md

许可证

MIT

作者

houaoran [email protected]

更新日志

3.0.10

• 添加 PersonTree 人员选择组件
• 支持自定义组件拖拽
• 优化打包配置
• 添加 peerDependencies 配置