表单设计器 ★
一句话：低代码表单的搭建工作台——四步向导「基础设置 → 数据绑定 → 表单设计 → 列表设计」把一张物理表变成能填、能查、能打印的运行时页面；本页讲清每一步配什么、哪些坑会在发布时才暴露、以及怎么在发布前用「体 检」自查。
先读这条：本页面没有未保存拦截
点返回箭头、点浏览器后退、切换侧边栏菜单、关闭标签页，都不会弹任何确认框，没保存的改动直接丢失。养成习惯：每配完一步就点右上角「保 存」。
功能在哪
- 入口：基础设施 → 在线开发 → 表单设计 列表页，点「新增」或行内「设计」进入；
- 地址栏路由：
/infra/online/editor?id={表单编号}（菜单本身是隐藏项，侧边栏看不到，只能从列表页进）； - 需要的权限：
infra:form-design:create（新增）/infra:form-design:update（设计、保存）。
界面认识
- 顶部左侧：返回箭头、表单名称（新建时显示「新建表单」）、状态标签（草稿 灰 / 已发布 绿 / 已发布有改动 橙）；
- 顶部中间：步骤条 1 基础设置 / 2 数据绑定 / 3 表单设计 / 4 列表设计。步骤可以直接点：往前跳不校验，往后跳要先通过当前步校验；表单类型为「纯表单」时没有第 4 步；
- 顶部右侧：「体 检」（保存过才出现）、「上一步」、「下一步」、主按钮「保 存」（下拉里还有「保存并关闭」「保存并发布」）；
- 头部没有「预览」按钮——想看效果要么发布后从菜单进运行时，要么在列表页「版本」抽屉里预览某个历史版本。
第 1 步：基础设置
| 字段 | 说明 |
|---|---|
| 表单名称 | 必填；列表与运行时页签都用它 |
| 表单编码 | 必填；只允许字母、数字、下划线，且以字母或下划线开头；失焦时即时查重，被占用提示「表单编码「{编码}」已被占用，请换一个」；发布后锁死不可改（提示原文：「表单已发布，编码不可修改 —— 运行时与菜单都通过它引用本表单。」） |
| 分类 | 字典「表单设计分类」：业务表单 / 基础数据 / 统计报表 / 其他 |
| 表单类型 | 纯表单（只有填写页）/ 表单+列表（额外生成列表页，需要配第 4 步）。提示原文：「纯表单只有填写页；表单+列表会额外生成列表页，需要在「列表设计」步骤配置列与查询条件。」 |
| 排序 / 备注 | 选填 |
新建时的默认值：表单类型=表单+列表、数据源=主库、主键列=id、主键策略=雪花算法、排序=0。
第 2 步：数据绑定
这一步决定数据落到哪张物理表。页面顶部一句话原文：「只绑定已有的物理表，不建表也不改表结构。配置规则见右侧文档。」——表结构归 DBA 管，平台只绑定；右上角「查看文档」打开七节说明抽屉（下文「进阶」摘了要点）。
主表四件套
| 字段 | 说明 |
|---|---|
| 数据源 | 默认主库（本系统自己的库）；其余选项来自 数据源配置。主表、副表、明细表必须在同一个数据源里——跨库没法用同一个事务 |
| 主表 | 可搜索；下拉项显示「表名（注释）」；system_ / infra_ / bpm_ 前缀的系统内置表被禁用并带红色「系统表」标签（只读关联可以用它们，比如 JOIN 用户表取昵称） |
| 主键列名 | 默认 id |
| 主键策略 | 雪花算法（推荐，要求 bigint 列）/ 数据库自增（绑老表可用）/ UUID（要求 varchar(32) 及以上）。策略与列类型对不上时页面立刻给红色警告，不必等发布 |
主表名旁有两个小图标：复制表名、查看这张表的数据（跳到 数据查看；表没登记时会提示「表 {表名} 还没有登记，请先到【数据模型】里导入这张表」）。
五个可选区块
| 区块 | 开了之后 | 默认 |
|---|---|---|
| 逻辑删除（可选） | 删除只改标记列、不发物理 DELETE，查询自动追加「列 = 未删除值」。表里有 deleted 列会被自动开启并按列类型推断值类型 | 列 deleted、值类型 数字、已删除 1 / 未删除 0 |
| 乐观并发锁（可选） | 更新时带「读出来时的版本号」做 WHERE 条件并 +1，版本对不上就拒绝提交。不开的话两个人同时编辑，后保存的会静默覆盖先保存的，双方都看到「保存成功」 | 版本列只能选整数列 |
| 数据变更日志（可选） | 每次修改记下「谁在什么时候把哪个字段从什么改成了什么」，详情页「变更记录」页签可看时间线。不开就没有任何办法知道旧值；只记主表字段，子表明细不记 | 关 |
| 系统字段自动填充（可选） | 按约定名自动探测审计列（creator / create_by / created_by、create_time / created_at / gmt_create 及对应的更新人/更新时间）；列名不符合约定时开「手动指定列名」逐列选。每行填充方式三选一：系统填充 / 表单填写 / 不填充 | 自动探测 |
| 关联表（可选） | 三类：一对一副表（与主表同增删改，主表太宽时拆表用）、一对多明细（对应表单里的子表控件）、只读关联（LEFT JOIN 展示，比如显示业务员姓名，不参与写入） | 空 |
「下一步」点了没反应？
数据绑定这一步没选主表时点「下一步」没有任何提示文案——页面就是不动。这不是卡死，是主表还没选。
第 3 步：表单设计
中间是画布，左侧是控件库（三个页签：组件 / 大纲 / 字段映射），右侧是属性面板。拖控件进画布即自动选中，右侧立刻可配。
控件库有什么
| 分组 | 控件 |
|---|---|
| 基础 | 单行输入、多行输入、密码输入、数字输入、开关、日期、日期区间、时间、时间区间、滑块、评分、颜色选择 |
| 选择 | 单选、多选、下拉选择、级联选择、树形控件、树形选择、穿梭框、关联表单、远程选择器、行政区划、字典选择器 |
| 高级 | 子表（明细）、文件上传、单图上传、多图上传、富文本、手写签名、计算公式 |
| 系统 | 组织选择器、系统值、单据编号 |
| 展示 | Iframe、提示、按钮、分割线、HTML、图片、条码/二维码、超链接、标签、文字、标题 |
| 布局 | 栅格布局、卡片、折叠面板、标签页、步骤条、表格布局、间距 等 |
有些控件「找不到」是故意的
内核自带的「表格表单」「分组」「用户选择器」「部门选择器」「接口选择器」等不在菜单里：它们的数据本模块存不进去（或已被替代：组织选择器、远程选择器）。历史表单若残留这类控件，发布时会被明确拒绝而不是静默丢数据。
字段映射：控件的值落到哪一列
左侧第三个页签「字段映射」把画布上每个控件对应到物理列（子表控件展开后逐字段映射）。
- 顶部「从 {主表名} 一键生成字段」：按列类型自动放控件（整数/小数→数字输入、日期→日期、布尔→开关、其它→单行输入），列不可为空自动勾必填；跳过
creator/create_time/updater/update_time/deleted/tenant_id这些审计列；成功提示「已生成 {N} 个字段」； - 有字段没映射时顶部警告条原文：「有 {N} 个字段还没有映射到物理列，提交时这些字段不会入库」——不是报错，是提醒：没映射的字段填了也白填；
tenant_id这类受保护列不允许被映射（否则等于让表单决定租户归属，会造成跨租户越权）。
属性面板里本平台多加的能力
选中控件后，右侧除内核配置外还有这些自研项：
| 能力 | 说明 |
|---|---|
| 格式校验 | 仅加在单行/多行/密码/数字输入上（下拉、单选的取值来自选项，配正则只会制造「选了却提交不了」）。内置 18 种格式（手机号、身份证、统一社会信用代码、车牌号、金额……），也可写自定义正则，并带「输入一个值试试」的试值框 |
| 内容不能重复 | 填写时即时查重 + 提交时服务端再查。它不能替代数据库唯一索引：两人同时提交同一个值，两次检查都会通过 |
| 选项来源 | 选项类控件三选一：静态数据 / 数据字典 / 数据接口 |
| 数据脱敏 | 手机号 / 身份证 / 银行卡 / 姓名 / 邮箱 / 自定义；下发前遮掩，库里仍是明文 |
| 数字增强 | 千分位显示、显示金额大写（只影响显示，落库仍是纯数字）；日期可配「相对默认值 + 偏移量」（如 N 天后） |
| 子表 | 合计行；分组标题可折叠；标签页容器可开「分步校验」（当前页校验不过不允许往后翻） |
逻辑与扩展（弹窗，不是步骤）
入口在右侧「表单配置」面板末尾的「逻辑与扩展」按钮（有问题时按钮带红色角标，下方提示「{N} 项配置有问题，保存前需要处理」）。弹窗三个页签：
- 联动规则：字段间显隐、必填、赋值的联动；顶部说明原文：「配置字段之间的联动，以及表单的业务逻辑扩展方式。联动规则会在提交时由服务端复算，前端绕不过去。」
- 跨字段校验：如「结束日期必须晚于开始日期」；
- 扩展方式：无 / 前端脚本 / 服务端扩展点（默认前端脚本）；选服务端扩展点但后端没有对应实现时，发布会被拦。
第 4 步：列表设计
只有「表单+列表」类型才有这一步，共八个页签：列配置、查询条件、分页设置、按钮设置、自定义按钮、详情页页签、打印模板、高级。右侧字段面板只在「列配置」「查询条件」两个页签出现（勾选哪些字段进列表 / 进查询区，带「已选 N / 总数」计数与全选/反选/清空）。
| 页签 | 配什么 |
|---|---|
| 列配置 | 显示序号、显示合计行（+合计列）、导出上限（默认 2 万，最大 20 万；超出部分不会被静默丢掉，文件名会标「前 N 条」）；每列的标题、宽度（最小/固定）、对齐、冻结、格式化（字典翻译/标签/日期/数字/百分比/布尔/超链接/图片/附件……）、可排序、同值合并 |
| 查询条件 | 每个查询项的标签、查询控件（文本框/下拉选择/日期/日期区间/数字/数字区间/是 否）、操作符（等于/包含/区间/为空……13 种，按控件类型限定可选项）。勾字段时自动推断控件类型 |
| 分页设置 | 启用分页（默认开，每页 20）、默认排序（字段 + 升/降序） |
| 按钮设置 | 操作列开关/标题/宽度、按钮折叠阈值（默认 3：行内按钮超过阈值时多出来的收进「更多」下拉）；内置按钮清单可开关、改文案、换图标、拖顺序。工具栏：新增/导入/导出/批量删除/批量打印/打印列表；行内：编辑/详情/变更记录/打印/删除 |
| 自定义按钮 | 给列表加「跳到大额复核页」「调某个数据接口」这类动作；位置可选工具栏/列表行内/详情弹窗；跳转地址支持 {字段} 插值 |
| 详情页页签 | 详情弹窗里除表单本体外再挂页签：变更记录（需开变更日志）或关联数据（按「关联字段 = 本记录主键」查另一张表单） |
| 打印模板 | 富文本里用 {字段} 写占位符、{#子表字段} 写明细循环行；右侧面板点一下即可插入 |
| 高级 | 表单呈现方式（居中弹窗 / 右侧抽屉 / 页内显示）、行内编辑、标签页筛选、树形列表、左侧树查询区、列设置、行分组、复杂表头 |
四组「二选一」，界面上会直接告诉你原因
- 树形 vs 分页：「树形列表已开启，分页不可用。要用分页请先关闭树形。」（分页会把父子行拆到不同页）
- 明细列 vs 行内编辑：明细列把一条主记录摊平成多行，改其中一行的主表值没有确定语义；
- 明细列 vs 树形：两种重排合不到一起；
- 行分组 vs 树形/明细/行内编辑：都在重排行结构，不能同时用。同值合并的可用条件也是这四者全关。
保存、体检、发布
- 「保 存」：成功提示「保存成功」（新建为「创建成功」）；「保存并关闭」保存后回列表；「保存并发布」保存后直接打开发布弹窗（发布流程见 表单设计）；
- 「体 检」：先保存、再拿库里那一份跑发布校验，弹窗标题「设计期体检」。没问题时显示「没有发现问题」+ 副标题「体检与发布走的是同一份校验，所以这张表单现在一定发得出去」；有问题时列出全部问题清单（「发现 {N} 个问题，发布会被拒绝」），按钮「重新体检」「关 闭」。
两种「版本冲突」不是一回事，补救动作也不同
- 业务数据行被他人改过（运行时填单/改单时）：「这条数据在你编辑期间已被他人修改，你的修改没有保存。请刷新后在最新数据上重新修改 —— 直接覆盖会把对方的改动悄悄抹掉」；
- 表单定义被他人改过（设计器里点保存时）：「这张表单在你编辑期间已被他人修改……」并追加「⚠️ 本页仍持有旧的版本号，继续点保存只会重复失败。请点「返回」重新进入本页取回最新内容，在其上重做本次修改。」——此时别反复点保存，返回重进才是正解。
视角对照
| 视角 | 看到什么 |
|---|---|
| 租户管理员 | 全部四步与发布；通常兼任「实施」角色，直接搭表单 |
| 普通员工 | 看不到本页；只用发布后生成的运行时菜单 |
| 套餐受限租户 | 菜单是否可见取决于套餐是否包含「表单设计」；不含时侧边栏没有入口 |
进阶：发布校验在拦什么
「体 检」与「发布」跑的是同一份校验，一次列全所有问题（用「；」拼成一条）。高频被拦项与对应改法：
| 现象（报错要点） | 改法 |
|---|---|
| 表({})中不存在列({}) | DBA 改过表结构；回字段映射重选列 |
| 主键策略选了「雪花算法」但主键列是 int | 换 bigint 列或改「数据库自增」 |
| 子表({})没有配置任何字段映射 / 表单里的子表控件({})没有配置对应的明细表 | 回数据绑定补明细表，或回字段映射给子表字段选列——否则明细填了也存不进去，接口还返回成功 |
| 列({})已配置为系统自动填充，不能同时在表单字段映射中使用 | 二选一：改填充方式为「表单填写」，或移除该字段的映射 |
| 字段({})引用的数据字典({})已停用 / 是懒加载模式 | 换字典或把字典改为全量下发 |
| 联动规则存在环形赋值 / 引用了不存在的字段 | 回「逻辑与扩展」打断环或删规则 |
| 自定义按钮 / 详情页页签 / 打印模板的配置问题 | 报错里直接点名是哪个按钮、哪个页签、哪个占位符，照着改 |
三个「只在当前页口径上算」的设计
合计行、行分组的「（N 条）」、组内小计都只统计当前页数据，不是全表——界面上已写明（「⚠️ N 是当前页的条数」）。要全表口径请用统计报表或数据接口。
自定义按钮的「权限点」不是访问控制
它只决定按钮画不画出来，不构成任何服务端约束——把它当访问控制会是彻底的安全假象。另外「调数据接口」动作的按钮目前沿用本表单自己的更新权限：能改这张表单的人就能点它上面的任何接口按钮。真要控权，请在数据接口与角色授权层面做。
常见问题
Q：点「下一步」没任何反应？ A：数据绑定步没选主表时就是静默不动（无提示文案）。选上主表即可。
Q：切去别的菜单再回来，配的东西没了？ A：本页没有未保存拦截，离开即丢。每步配完先点「保 存」。
Q：为什么状态变成「已发布有改动」？ A：只要保存过草稿（包括点「体 检」，它会先保存一次），而线上版本还是旧的，就是这个状态。重新发布才会把草稿推上线。
Q：子表里再套子表（多级明细）支持吗？ A：不支持。嵌套的子表控件会被忽略（界面无提示，仅控制台告警）。需要多级结构时拆成两张表单，用详情页「关联数据」页签串起来。
Q：打印模板里放了 {字段} 但印出来是空白？ A：占位符只能引用主表字段、主键与审计字段；子表明细必须用 {#子表字段} 且放在表格的某一行里。条码/二维码控件的值印出来是那串文本而不是图形；富文本印出来是转义后的 HTML 原文。
Q：列表上空格子显示什么？布尔值显示什么？ A：空格子显示「-」；布尔值显示「是」/「否」；合计行行首是「合计」，分组行行首带「▸ 」。