更新记录

1.0.1（2025-08-01）

1. 初次发布通用表单组件

平台兼容性

uni-app(4.75)

uni-app x(4.75)

📦 DynamicForm 组件文档

基于 uni-app + Vue3 + setup + UTS，封装的动态表单组件 支持 JSON Schema 配置，结合 uni-ui 实现微信小程序端灵活表单构建： ✅ 普通字段渲染（input、select、checkbox、switch、date、file 等） ✅ 嵌套对象字段（type: 'object'） ✅ 数组字段（type: 'array'）支持动态增删 ✅ 插槽自定义渲染 ✅ 自定义校验 & 异步选项加载

📌 功能概览

• 表单渲染完全由 schema 配置驱动
• 支持普通字段、数组子表单、对象嵌套字段
• 支持插槽自定义字段内容
• 异步 / 静态选项（如下拉、复选框）
• 表单验证与清空
• 提供 validate / reset 方法供外部调用

🛠️ 基本用法

1️⃣ 安装依赖

需在项目中安装并配置：

• uni-ui
• path 工具（自行封装，用于 get/set 嵌套字段值）

2️⃣ schema 配置示例

const formSchema = [
  { name: 'name', label: '姓名', type: 'input', required: true },
  { name: 'gender', label: '性别', type: 'select', options: [
      { value: 'male', label: '男' },
      { value: 'female', label: '女' }
    ] 
  },
  { name: 'hobbies', label: '爱好', type: 'checkbox', options: async () => {
      return [{ value: 'reading', label: '阅读' }, { value: 'sports', label: '运动' }]
    } 
  },
  { name: 'isStudent', label: '是否学生', type: 'switch' },
  { name: 'birth', label: '出生日期', type: 'date' },
  { name: 'attachments', label: '附件', type: 'file' },
  {
    name: 'contacts',
    label: '联系人',
    type: 'array',
    itemSchema: [
      { name: 'contactName', label: '姓名', type: 'input' },
      { name: 'phone', label: '电话', type: 'input' }
    ]
  },
  {
    name: 'address',
    label: '地址信息',
    type: 'object',
    itemSchema: [
      { name: 'province', label: '省份', type: 'input' },
      { name: 'city', label: '城市', type: 'input' }
    ]
  }
]

3️⃣ 使用组件

<template>
  <DynamicForm
    ref="dynamicFormRef"
    :schema="formSchema"
    v-model="formModel"
  >
    <!-- 自定义插槽示例 -->
    <template #name="{ item }">
      <uni-easyinput v-model="formModel.name" placeholder="自定义姓名输入" />
    </template>
  </DynamicForm>

  <button @tap="submit">提交</button>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import DynamicForm from '@/components/DynamicForm.vue'

const formModel = ref({
  name: '',
  gender: '',
  hobbies: [],
  isStudent: false,
  birth: '',
  attachments: [],
  contacts: [],
  address: {}
})

const dynamicFormRef = ref()

async function submit() {
  const valid = await dynamicFormRef.value?.validate()
  if (valid) {
    console.log('提交数据：', formModel.value)
  }
}
</script>

🧩 组件结构

🌱 DynamicForm.vue

• 基于 <uni-forms> 渲染整个表单

• 根据字段类型：

  • 普通字段：调用 <FormItem />
  • 数组字段：动态增删项
  • 对象字段：嵌套渲染子字段
• 提供 validate() / reset() 方法

🌿 FormItem.vue

• 基于 <uni-forms-item> 包裹
• 根据 type 动态渲染对应组件

• 支持：

  • 输入框（input / textarea）
  • 下拉选择（select）
  • 多选（checkbox）
  • 开关（switch）
  • 日期选择（date）
  • 文件上传（file）
• 支持 options 为静态或异步

⚙️ 参数 & 插槽

插槽

支持为任意字段通过 #字段名 自定义渲染：

<template #name="{ item }">...</template>

🛡️ 表单方法

✏️ 自定义校验

在 schema 中添加 rules：

{ 
  name: 'name', label: '姓名', type: 'input', 
  rules: [{ required: true, errorMessage: '姓名不能为空' }]
}

📦 依赖

• uni-ui（uni-forms, uni-easyinput, uni-data-select, etc）
• 自行封装的 get / set 工具用于深层字段操作

🎨 样式

默认内置：

• .form-array-block, .form-object-block：容器
• .form-array-title, .form-object-title：标题
• .form-array-item：子项
• .form-array-actions, .form-array-footer：操作区域

可按需覆盖或扩展。

✅ 总结

这个动态表单组件：

• JSON Schema 驱动，适合中后台 / 配置化场景
• 支持复杂场景：数组、嵌套对象、异步选项
• 插槽支持让你灵活控制部分字段
• 基于 uni-ui，完美适配微信小程序

如果需要，我还可以帮你写 更详细文档 或 示例仓库，要的话直接告诉我！ 🚀