更新记录

1.0.2（2026-05-09）

组件属性对齐与修复（wot-design-uni v2 权威对齐）

• wd-slider：移除无效的 show-value，改用 show-extreme-value + popover-visible，补齐 theme / range / vertical 透传
• wd-textarea：移除无效的 rows 属性，仅保留 auto-height；子表单补齐 placeholder
• wd-switch：子表单同步主表单的 activeText / inactiveText 文案显示；主/子表单统一使用 Web 端 switchWidth 配置驱动，替代写死的 36rpx
• wd-rate：子表单补齐 showText + texts[] 文本显示，以及 readonly / allow-half 逻辑，对齐主表单
• wd-button（append-button）：补齐 plain（variant）/ round 属性透传
• wd-input-number：去除不支持的 controls-position 绑定
• VformCascader：封装组件透传 checkStrictly / valueKey / textKey / childrenKey，支持任意层级单选

级联/区域组件增强

• form-cascader：完善静态 + 懒加载双模式切换（对齐 wd-cascader v2 能力）
• form-region：省市区加载路径与选项结构稳健化

文件/图片上传健壮性

• form-upload：多选字段名统一为 multipleSelect
• wd-upload @success 回写 OSS URL；beforeRemove 返回 Promise 确保拦截生效
• reupload=true 场景禁用图片预览，避免冲突
• uni.uploadFile 响应 URL 空值校验，失败项打标，前端 URL 稳健化处理

子表单 / 弹窗 / Picker

• vform-subform：行内排版 + 弹窗选择模式统一；补齐占位符、文案、Switch/Rate 属性
• 适配 wot-ui v2 picker 纯弹窗模式，手动添加触发层避免空白不可点

文档化（types.ts 顶部注释）

• 说明 wot-ui 无对应实现、已忽略的 Web 端属性：
  • textarea.autoHeightMaxRows
  • select.allowCreate / remote / remoteMethod
  • date / time 的 format / valueFormat
  • slider.showTooltip / formatTooltip
  • rate.showScore 模板
  • button.circle
• 说明子表单 radio/checkbox/select 统一采用弹窗选择（行内空间有限），与主表单 UX 的差异

1.0.1（2026-02-02）

1.0.0（2026-02-02）

基于 VForm 表单设计器的 uni-app 端渲染组件首版发布

支持的组件

基础字段组件

• input 输入框
• textarea 文本域
• number 数字输入框
• radio 单选框
• checkbox 多选框
• select 下拉选择
• switch 开关
• rate 评分
• slider 滑块
• color 颜色选择器

日期时间组件

• date 日期选择
• time 时间选择
• date-range 日期范围
• time-range 时间范围

高级组件

• cascader 级联选择
• picture-upload 图片上传
• file-upload 文件上传
• rich-editor 富文本编辑器
• sub-form 子表单

容器组件

• grid 栅格布局
• table 表格布局
• tab 标签页
• step 步骤表单

展示组件

• static-text 静态文本
• html-text 富文本展示
• divider 分割线
• button 按钮

技术特性

• 基于 Vue 3 + TypeScript 开发
• 使用 wot-design-uni 作为基础组件库
• 统一 VForm JSON 数据格式（widgetList + formConfig）
• 与 PC 端 FormDesigner 设计器数据互通
• 完善的 modelValue 空值处理，避免类型错误

1.0.0（2026-02-02）

1.0.5（2026-02-02）

【修复】修复 radio/select 组件 defaultValue 为 null 时传递给 wd-select-picker 导致类型检查失败的问题 【修复】修复 time-range 组件 getTimeRangeValue 返回 null 导致 wd-datetime-picker 类型错误的问题 【优化】getDefaultValue 函数增强类型安全，根据组件类型返回合适的默认值，避免 null 值传递 【优化】统一所有 Wd 组件的 modelValue 空值处理，确保符合 String | Number | Boolean | Array 类型约束

平台兼容性

uni-app(4.57)

uni-app x(3.91)

vform-render - 基于 VForm 的 uni-app 动态表单渲染组件

与 PC 端 FormDesigner（VForm 设计器） 配合使用，通过统一的 JSON 数据结构，实现「一次设计，跨端渲染」。

• 技术栈：Vue 3 + TypeScript + wot-design-uni
• 数据格式：VForm 标准 JSON（widgetList + formConfig）
• 跨端支持：H5 / App（Android / iOS / HarmonyOS）/ 各家小程序
• 设计目标：Web 端设计器 ↔ 移动端渲染器的字段与属性一致性

一、快速开始

1. 安装依赖

本组件依赖 wot-ui v2（必需）、sp-editor（富文本编辑）、mp-html（富文本展示）。富文本相关依赖按需引入。

2. 基础使用

<template>
  <vform-render
    ref="formRef"
    :form-json="formJson"
    v-model="formData"
    :base-path="basePath"
    :header="header"
    :disabled="false"
    @onSave="handleSave"
    @onChange="handleChange"
    @onValidate="handleValidate"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { VFormJson } from '@/uni_modules/vform-render/components/vform-render/types'

const formRef = ref()
const formData = ref<Record<string, any>>({})
const basePath = 'http://127.0.0.1:8080'
const header = { Authorization: 'Bearer xxx' }

// 由 FormDesigner 生成的 JSON
const formJson = ref<VFormJson>({
  widgetList: [],
  formConfig: {}
})

function handleSave(data: Record<string, any>) {
  console.log('表单提交数据：', data)
}
function handleChange(field: string, value: any, data: Record<string, any>) {
  console.log('字段变化：', field, value)
}
function handleValidate(valid: boolean, errors?: any[]) {
  console.log('验证结果：', valid, errors)
}
</script>

3. 组装 JSON（从后端模型）

const formJson = {
  widgetList: JSON.parse(modelData.rule),   // FormDesigner 导出的 widget 数组
  formConfig: JSON.parse(modelData.options) // FormDesigner 导出的表单级配置
}

二、API

Props

Events

方法（通过 ref 调用）

三、支持的组件（VForm widget.type）

基础字段

日期时间

高级

容器

展示

四、数据格式

interface VFormJson {
  widgetList: Widget[]     // 组件列表
  formConfig: VFormConfig  // 表单级配置
}

interface VFormConfig {
  labelWidth?: number
  labelPosition?: 'left' | 'right' | 'top'
  labelAlign?: string
  size?: string
  // ...更多配置
}

interface Widget {
  id: string
  type: string
  options: WidgetOptions
  formItemFlag?: boolean
  widgetList?: Widget[]    // 容器组件的子组件列表
}

五、依赖说明

六、与 FormDesigner 协同

1. PC 端设计：使用 FormDesigner 完成表单设计
2. 后端保存：widgetList → rule、formConfig → options
3. 移动端渲染：接口返回后组装为 VFormJson 即可

const formJson = {
  widgetList: JSON.parse(modelData.rule),
  formConfig: JSON.parse(modelData.options)
}

七、注意事项

1. modelValue 类型约束：wot-design-uni 组件不接受 null，本组件内部已处理。请确保传入 String | Number | Boolean | Array
2. 文件上传：需正确配置 base-path 与 header（Authorization 等）
3. 图片/文件多选：使用字段 multipleSelect；uni.chooseImage 单次最多 9 张（平台限制）
4. 子表单 UX 差异：行内空间有限，子表单中 radio/checkbox/select 统一使用弹窗模式
5. Picker 触发层：wot-ui v2 的 Picker 为纯弹窗模式，本组件已手动添加触发层，无需额外处理
6. 富文本依赖：rich-editor / html-text 需额外安装 sp-editor / mp-html

wot-ui 未覆盖的 Web 端属性（已文档化忽略）

八、版本

当前版本：1.0.2。变更记录详见 changelog.md。