表单设计器

表单设计器是 RuoYi Office 的在线拖拽式表单能力，适合快速搭建轻量申请、临时审批、流程原型和字段较少的内部表单。它可以单独维护表单配置，也可以和工作流 BPM 结合，作为流程模型中的“流程表单”使用。

本页是“表单设计器”主教程。与它强相关的流程表单接入、上下文变量、数据查询已经放在左侧“表单设计器”下面，便于按操作链路阅读。

入口与定位

在管理端进入 流程中心 → 流程表单，可以查看、搜索、新增、复制、编辑和预览流程表单。当前工程代码目录仍位于 BPM 模块下，但从能力归类上，它属于“表单开发”的基础能力。

能力	说明
在线设计	通过 form-create 设计器维护字段、布局、校验、默认值和事件
流程表单	作为 BPM 模型的 NORMAL 表单，发起流程时在线渲染
动态控制	支持显隐、禁用、必填和事件脚本
数据查询	流程表单值以 Flowable 变量保存，可用于排查和轻量统计
快速试运行	适合先验证流程和字段，再决定是否升级为业务表单

设计器界面

表单设计器主要分为顶部操作区、左侧组件区、中间画布和右侧配置区。全景图用于定位，配置细节建议看下面的局部图。

区域	主要操作	注意点
顶部操作区	保存、预览、清空、撤销重做	保存只保存表单配置，不会自动发布流程
左侧组件区	拖拽字段、容器、系统字段	优先选择贴近业务含义的组件
中间画布	排版、复制、删除、调整字段顺序	字段 key 稳定后不要随意改
右侧配置区	配置表单属性、字段属性、动态属性、事件	简单规则用动态属性，复杂联动用事件

左侧组件区

左侧按类型提供组件，常用分类包括基础组件、子表单组件、容器组件、辅助组件、布局组件和系统字段。可以直接拖拽到中间画布。

常用组件建议：

• 普通字段优先使用输入框、选择器、日期、时间、文件上传等基础组件。
• 需要人员、部门、字典或接口数据时，优先使用系统字段。
• 字段很多时用栅格、分组、标签页拆分，不要把所有字段堆在一个长表单里。
• 明细类数据可以使用数据表格、Vxe 数据表格或表格表单，但正式业务明细建议评估业务表单。

组件选择建议：

业务字段	推荐组件
姓名、标题、事由	输入框、多行输入框
金额、数量、时长	数字输入框、金额、时长
部门、人员、字典	部门选择器、用户选择器、字典选择器
附件、图片	文件上传、单图上传、多图上传
明细行	数据表格、Vxe 数据表格、表格表单

中间画布

中间画布展示最终运行时表单结构。选中字段后，可以在字段上进行复制、删除、排序，也可以继续调整布局。

设计建议：

• 字段 key 一旦进入流程使用后不要随意修改，否则历史变量会保留旧 key。
• 必填字段要和真实业务最小提交要求一致，避免审批人无法处理异常单据。
• 文件上传、明细表格、富文本等复杂组件要提前验证移动端或详情页展示效果。

右侧配置区

右侧用于配置表单整体属性或当前选中组件的属性。表单级配置包括表单名称、布局、标签宽度、提交按钮、重置按钮、表单事件等；字段级配置包括标签、字段名、默认值、校验规则、动态属性、事件脚本等。

常用配置：

配置	用途
字段名	运行时变量 key，后续查询、表达式和脚本都依赖它
标签	用户看到的字段名称
校验规则	控制必填、格式、长度等
动态属性	控制隐藏、禁用、必填等运行时状态
表单事件	编写复杂联动脚本，例如 onMounted

操作流程

1. 新增或编辑表单

进入 流程中心 → 流程表单，点击“新增流程表单”创建新表单；也可以在列表中选择“编辑”打开已有表单。复制适合基于已有表单快速创建变体。

2. 拖拽组件并配置字段

从左侧选择组件拖入画布，在右侧配置字段名、标签、选项、默认值和校验规则。字段名建议使用稳定英文或业务字段名，例如 amount、reason、applyDeptId。

字段命名建议：

类型	示例
文本	title、reason、remark
金额	amount、applyAmount、approveAmount
组织	deptId、deptName、applyUserId
附件	attachment、fileIds
明细	detailList、itemList

3. 配置动态属性

设计器支持把以下属性追加到配置中：

属性	作用
hidden	控制字段是否隐藏
props.disabled	控制字段是否禁用
$required	控制字段是否必填

例如只在待办审批页开放字段，可以配合流程上下文变量：

GET_DATA("$globalData.bpmProcess.viewType") !== "todo"

更多变量见 流程表单上下文变量。

如果只是“某个审批节点可编辑、其他节点只读或隐藏”，优先使用 表单字段权限控制，不要把节点权限全部写成脚本。

4. 配置表单事件

如果显隐、禁用、必填需要多字段联动，可以在“表单事件”中写脚本。常用事件是 onMounted：

function onMounted(api) {
  const bpm = api.getData?.("$globalData.bpmProcess") || {};
  const readonly = bpm.viewType !== "create";

  ["amount", "reason", "attachment"].forEach((field) => {
    api.disabled?.(readonly, field);
  });
}

简单规则优先用动态属性，复杂联动再用事件脚本。

5. 保存表单信息

点击顶部“保存”，填写表单名称、单据类型编码、状态和备注后保存。保存后表单会出现在流程表单列表中，可被流程模型引用。

截图时只打开保存弹窗用于说明，不需要在演示环境重复提交保存。

6. 绑定流程模型

进入 流程中心 → 流程模型，在“表单设计”步骤选择“流程表单”，再选择刚维护好的表单。发布流程后，用户在“发起流程”中即可填写该在线表单。

与业务表单的选择

维度	流程表单	业务表单
数据存储	Flowable 变量	独立业务表
开发成本	低，在线配置	中高，需要前后端开发
页面能力	受设计器组件约束	可完全定制
查询统计	适合简单查询	适合复杂报表与业务分析
推荐场景	临时审批、轻量表单、流程试运行	OA、HRM、CRM、合同、项目等正式业务闭环

如果后续需要业务台账、列表筛选、明细表生命周期、移动端独立页面、复杂附件或状态机，应迁移为 业务表单接入。

延伸阅读

• 流程表单上下文变量：在动态属性和事件脚本中读取流程信息。
• 流程表单数据查询：使用 SQL 查询 NORMAL 类型表单的流程变量数据。
• 表单字段权限控制：统一说明流程表单和业务表单的字段权限配置。