更新记录

1.0.4（2026-07-26）

文档与体验资源

• 新增「在线体验」入口：管理端地址、测试账号、iOS（App Store 搜索「流程一点通」）、Android 体验安装包
• 新增「功能预览」章节：随包附带 App 端渲染截图与 Web 端 FormDesigner 设计效果对照图（images/preview/）
• 随包附带 Android 体验安装包 __UNI__0D0B8FF__20260726123657.apk

1.0.3（2026-07-26）

弹层渲染修复（root-portal 化）

• 全部弹层组件补齐 :root-portal="true" + :z-index="1000"，脱离父容器渲染到页面根节点，根治弹层被 scroll-view / 容器 overflow 裁剪、被固定定位元素遮挡的问题
• 覆盖范围：主表单 wd-picker / wd-calendar / wd-datetime-picker（含 auto-crud 行内编辑）、子表单全部 picker、form-cascader 级联弹窗、form-editor 富文本弹窗，以及审批单 / 部门 / 岗位 / 颜色选择弹窗

新增属性

• hideOperationWidgets（Boolean，默认 false）：详情态隐藏操作触发类 widget（button / button-group / 输入框 appendButton）
  • 与 disabled 解耦：disabled 表达"可见但不可编辑"，hideOperationWidgets 表达"操作触发器整体不渲染"
  • 适用场景：待办详情、数据查看页等只读入口

公式引擎增强

• 新增 sum_unique_days(arrayName) / sum_unique_days(arrayName, "dateField") 聚合函数
  • 单参：按子表每行 start_time ~ end_time 区间展开日历天并全局去重计数（出差/请假天数场景，跨行重叠日期不重复计）
  • 双参：仅取指定日期字段的日期部分去重计数

子表单日期/时间修复

• 修复子表内 date / time / date-range / time-range 字段直接输出原始值，syncRoster / autoFetch 带出的毫秒时间戳被显示成 "1459440000000" 的问题，显示值统一按 format 格式化（与主表单 getPickerDisplayValue 对齐）
• 选择确认后按 valueFormat 序列化再写回行数据（与主表单 applyValueFormat 对齐），保证提交格式一致，避免存入毫秒时间戳

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 的差异

平台兼容性

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 端设计器 ↔ 移动端渲染器的字段与属性一致性

在线体验

• 管理端（FormDesigner 表单设计器）：https://oam.yb2033.com/
• 测试账号：***  /  密码 Admin@123
• iOS：App Store 搜索「流程一点通」
• Android：安装插件包内附带的体验安装包 __UNI__0D0B8FF__20260726123657.apk

功能预览

截图位于插件包内 images/preview/ 目录，导入插件后可在本地查看。

示例一	示例二	示例三	示例四

Web 端 FormDesigner 设计效果对照：

一、快速开始

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。