自定义表单
标准版及以上商业版功能
校对日期:2026-11-17。需要商业版标准版及以上(表单审核中的退回、委托、转办需高级版)。
自定义表单用来在前台收集在线报名、加盟意向、意见征集这类结构化信息。每一种表单是一个表单类型:字段由它绑定的表单模型决定, 另外规定谁可以填写、是否要审核、能否在前台公开浏览。访客或后台人员每提交一次,就在这个类型下产生一条表单。
配置顺序:建表单模型并设计字段 →(需要审核时)部署表单审核流程 → 新增表单类型 → 在前台放入口。 导入了演示数据的站点自带“在线报名”“加盟意向”两个表单类型和同名的表单模型,可以对照着看。
一、界面
进入 互动 → 表单管理。
- 左侧 是本站的表单类型。上方按名称搜索;搜索框旁的“+”是 新增类型;鼠标移到某一行上出现 编辑类型; 拖动行可调整类型的先后,前台列出表单类型时也按这个顺序。每行右边的数字是该类型下的表单数(已删除的也算),停用的类型标有 已停用。 选 全部 则跨类型列出所有表单。
- 右侧上方 是所选类型的信息:录入模式、是否 前台可浏览、绑定的模型和审核流程,以及 编辑类型、删除类型。
- 右侧下方 是表单列表,按状态分页签:全部、已审核、草稿、待审核、审核中、已删除、已退回。
二、设计表单字段
表单有哪些字段由表单模型决定,表单类型只是选用它:
- 进入 配置 → 模型管理,切到 表单模型 页签,新增一个模型(如“在线报名”)。
- 在这一行点 自定义字段,在设计器里加入字段,设置字段代码、字段名称、是否必填等。 设计器的用法见模型管理的“自定义字段”一节。
与表单有关的几点:
- 字段代码 是模板和接口里读取字段的名字,如
${form.。customs['phone']} - 列表中显示:开启后表单管理的列表多一列显示该字段;没开的字段可以在列表工具栏的 列设置 里打开。
- 单选、多选、下拉字段的选项来自字典,见字典管理。
- 保存时只保留模型里定义的字段,提交的其它内容被丢弃。已有表单的类型换了模型,或字段改了代码、被删除,对不上的字段不再显示。
- 默认主题的前台提交页不支持上传类字段(显示“暂不支持文件上传”),这类字段只能在后台录入;富文本、Markdown 字段在前台是普通的多行文本框。
三、新增表单类型
在左侧点“+”(新增类型),填写:
| 字段 | 说明 |
|---|---|
| 名称 | 类型的显示名称 |
| 模型 | 本站私有或全局共享的表单模型 |
| 审核流程 | 留空则无需审核,提交后即为“已审核”;选了流程,提交后先进入审核,见“表单审核”一节 |
| 表单列表模板 | 前台表单列表页 /form-list/ 的模板,候选是当前主题 templates/ 下以 form_list 开头的文件。留空则前台没有列表页 |
| 表单详情模板 | 前台单条表单页 /form-item/ 的模板,候选是以 form_item 开头的文件。留空则前台没有详情页 |
| 录入模式 | 谁可以在前台填写:前台游客 任何访客;前台用户 登录的会员;仅后台用户 只能在表单管理里录入。新增时默认 仅后台用户 |
| 前台可浏览 | 是否在前台展示已提交的数据。关闭时,列表页、详情页和读取表单的接口都不可用。默认关闭 |
| 是否启用 | 关闭后停止收集:前台不再列出这个类型,提交页打不开,提交被拒绝;已开放的列表页、详情页不受影响。默认开启 |
- 审核流程只能选本站已部署、类别为 表单审核 的流程。
- 删除类型:类型下还有表单(已删除状态的也算)时按钮置灰,先把这些表单 彻底删除。表单不随类型级联删除。
前台可浏览会公开提交的内容。 开启后,已审核的表单出现在前台列表页,详情页和接口能读到它的全部字段(提交者的 IP 不公开); 待审核、审核中、已退回、已删除和草稿状态的表单,前台始终看不到。默认主题的通用详情页 form_item.html 逐项列出所有字段; 演示的“在线报名”“加盟意向”页面把联系电话、电子邮箱打码显示,不显示地址。 收集手机号、住址等个人信息的表单请关闭这一项,或改写模板只展示可以公开的字段。
四、访客填写与提交
| 地址 | 模板 | 内容 |
|---|---|---|
/form-type | sys_form_type | 已启用、录入模式为前台游客或前台用户的表单类型 |
/form-create/ | form_submit | 提交页,按模型的字段生成输入框 |
/form-list/ | 类型的表单列表模板 | 需开启前台可浏览,只列出“已审核”的表单 |
/form-item/ | 类型的表单详情模板 | 需开启前台可浏览,只显示“已审核”的表单 |
- 类型停用时提交页返回 404;录入模式为 前台用户 时,未登录的访客打开提交页会先转到登录页;仅后台用户 的类型,提交页和提交接口都拒绝。
- 地址里的类型、表单须属于当前站点,否则返回 404;提交时类型不属于当前站点的,提交被拒绝。
- 提交时服务端检查必填字段,缺值时提示““字段名称”为必填项”。上传类字段不在检查之列:前台不能上传文件,这类字段设为必填也只约束后台录入。
- 每次提交都要通过人机验证(场景
form):同一 IP 一小时内的提交未达“免验证提交次数”(默认 3)时在后台静默完成, 达到后弹出可见验证,见验证码的“设置项”一节。除此之外没有提交次数上限。 - 类型没有审核流程时,提交后直接是“已审核”,开启了前台可浏览就立即出现在前台列表页;有审核流程时为“待审核”,通过后才公开。
- 系统记录提交者的 IP,只在后台显示。登录的会员提交时录入人是会员本人,未登录的访客记为匿名。提交后访客不能自己修改或撤回。
五、处理表单
在 互动 → 表单管理 里:
- 新增:先在左侧选中一个类型(选“全部”时不可用),填写后点 提交 或 存为草稿。后台录入不受录入模式和是否启用的限制,提交后的状态与前台提交相同。
- 编辑:双击行或点 编辑。对话框下方只读显示录入人、修改人、录入日期、修改日期、组织、IP。 保存只改内容不改状态:已退回的表单改好后要再点 提交 才会重新送审。
- 提交:草稿、已退回、已删除的表单可以提交(可多选)。无审核流程的类型直接变为已审核,有流程的进入流程。
- 删除:表单移到“已删除”,前台列表不再显示;正在审核的表单同时撤销其流程。彻底删除 从数据库删除,不能恢复。
- 拖动行首的图标调整顺序(需要“调整排序”权限),新表单排在最前,前台列表默认也按这个顺序。按某一列排序后不能拖动。
- 查询条件除录入人、录入日期等通用项外,还有模型里每个非上传字段的条件。流程图 显示有流程的表单走到了哪一步。
| 状态 | 含义 |
|---|---|
| 草稿 | 后台新增时点了 存为草稿 |
| 待审核 | 提交到有审核流程的类型,等待第一个审核环节 |
| 审核中 | 已通过前面的环节,等待后面的环节 |
| 已审核 | 无审核流程的类型提交后,或流程最后一个环节通过后。前台只显示这个状态的表单 |
| 已退回 | 审核人点了 拒绝;鼠标悬停在状态上可见退回原因 |
| 已删除 | 点了 删除 |
表单管理只列出数据权限范围之内的表单;有审核流程的类型,已审核、审核中的表单不能再修改,除非角色有“全部状态权限”或自己是当前审核人。 详见文章数据权限的“表单管理与表单审核”一节。
六、表单审核
给表单类型选了审核流程后,提交的表单要按流程逐级通过才算“已审核”。流程在 配置 → 流程模型 里新增(类别 选 表单审核)、 设计审核环节和审核人、部署,做法与文章审核相同,见文章审核流程的“新建流程”“设计流程”“部署”三节; 部署后到表单类型的 审核流程 里选它。
审核在 互动 → 表单审核 进行。左侧只列出有待自己审核的表单的类型,右侧是分配给自己(或自己的角色、组织为候选)的任务,按到达时间倒序:
- 通过:在“审核通过”对话框里可填写审批意见(环节设置了表单项时一并填写)。最后一个环节通过后表单变为已审核,否则为审核中。 勾选多行可批量通过。
- 拒绝:填写退回原因(必填,不超过 300 字),流程结束,表单变为“已退回”。可批量拒绝。
- 退回(高级版):退回到本流程已经走过的某个环节。委托、转办(高级版):把任务交给其他人,对方须看得到这个任务。
- 编辑:打开表单,可以修改内容并保存后再审核;有未保存的修改时审核按钮不可用。流程图 显示流程进度。
控制台首页的待办里,“待审核表单”进入表单审核,“我的已退回表单”是自己录入、被拒绝的表单,进入表单管理的“已退回”页签。
七、权限
在 用户 → 角色管理 的权限设置里,互动 下有两组:
| 权限 | 作用 |
|---|---|
| 表单管理 → 列表 | 进入表单管理,查看表单类型和表单列表 |
| 表单管理 → 新增、编辑 | 新增表单;打开、修改表单 |
| 表单管理 → 调整排序、提交、删除、彻底删除 | 列表上的同名操作 |
| 表单管理 → 新增类型、编辑类型、删除类型 | 维护表单类型;拖动类型排序也需要“编辑类型” |
| 表单审核 → 列表、通过、拒绝 | 进入表单审核并处理任务 |
| 表单审核 → 退回、委托、转办 | 同名的审核操作。高级版及以上才有,标准版的权限树里不显示这三项 |
审核人在表单审核里打开、修改表单,还需要“表单管理 → 编辑”。
八、模板、标签与接口
| 标签 | 用途 |
|---|---|
[@FormTypeList; formTypeList] | 表单类型列表。默认只取已启用、录入模式为前台游客或前台用户的类型;mode 指定模式(如 '0,1,2',空串为全部),isViewable 按前台可浏览筛选 |
[@FormList typeId=…; beans]、[@FormPage typeId=…; pagedList] | 某个类型的表单列表 / 分页。typeId 必填,类型须开启前台可浏览,否则报错;只取已审核的表单,默认按表单管理里的顺序;可加 orgId、userId |
[@Form id=…; bean] | 按 ID 取一条表单。只取本站、已审核、类型开启了前台可浏览的表单,否则 bean 为空 |
字段值从 customs 读取,如 ${bean.;条数、分页、排序等通用参数见模板标签与 API 的通用参数。
这些标签只在标准版及以上存在。首页、侧栏等任何版本都会渲染的模板用到它们时,要包在 [#if config. 里, 否则在低版本上整页报错(form_*、sys_form_type 这些只由表单页面渲染的模板不用)。默认主题的侧栏组件 snippets/ 也是这样包起来的:
[#if config.commercialTier gte 2]
[@FormTypeList limit=5; formTypeList]
[#list formTypeList as bean]<a href="${dy}/form-create/${bean.id?c}">${bean.name}</a>[/#list]
[/@FormTypeList]
[/#if]提交页。 form_submit 可用的变量是 formType 和 model(字段在 model.fieldList),列表页模板有 formType,详情页模板有 formType、form。 默认主题用 snippets/ 生成输入框,把 siteId、typeId、customs(字段代码 → 值)和人机验证的 captcha、captchaToken、website(蜜罐,留空) 以 JSON POST 到 ${api}/form。${api} 使用前台会话,须带 CSRF 令牌,见前台表单与 AJAX 的 CSRF 令牌的“AJAX 提交”一节。
| 方法 | 地址 | 说明 |
|---|---|---|
| GET | /api/form-type | 已启用、录入模式为前台游客或前台用户的表单类型 |
| GET | /api/、/api/ | 已审核的表单,类型须开启前台可浏览 |
| GET | /api/form/{id} | 一条已审核的表单,类型须开启前台可浏览 |
| POST | /api/form | 提交表单,参数同上 |
读取表单的接口不返回提交者的 IP。
演示数据。 主题可以在 seed/ 里带表单类型:名称、绑定的表单模型名称、两个模板、录入模式、前台可浏览、是否启用。 审核流程、排序和已提交的表单不在其中。表单类型在任何版本都会随主题导入,升级到标准版后即可使用。种子文件的写法见组件、区域与演示数据的“内容种子”一节。
预览模板。 设计 → 模板 里的 预览 这样找地址:sys_form_type 打开 /form-type;form_submit 打开第一个已启用、录入模式为前台游客或前台用户的类型的提交页 (前台用户模式以当前管理员的预览身份打开);表单列表模板要有一个开启了前台可浏览的类型选用它,打开 /form-list/; 表单详情模板同样要有类型选用它,并且该类型至少有一条已审核的表单,打开最新的一条的 /form-item/。 其它模板的预览规则见模板编写的“预览单个模板”一节。
九、常见问题
- 打开提交页显示 404。 表单类型已停用,或类型 ID 不对。录入模式为“前台用户”时,未登录会先转到登录页。
- 列表页、详情页打不开。 类型没有开启前台可浏览,或者没选表单列表模板 / 表单详情模板;详情页还要求表单是“已审核”。侧栏的“自定义表单”组件把每个类型都链接到列表页,没开前台可浏览的类型在那里点开会报错。
- 提交成功了,前台列表里看不到。 前台只列出“已审核”的表单,有审核流程的类型要等审核通过;也可能被后台删除了。
- 提交时提示“请完成人机验证后再提交”或“图片验证码不正确”。 同一 IP 一小时内的提交达到了免验证次数,需要完成弹出的验证;答错时重新作答。
- 删除类型的按钮是灰的。 类型下还有表单,包括已删除状态的,先在“已删除”页签里把它们彻底删除。
- 删除用户或组织时提示“表单模块使用了该数据,请先到“互动 - 表单管理”处删除相关数据”。 该用户录入过表单,或该组织下有表单。先在表单管理里按录入人、组织查出这些表单并彻底删除。
- 保存类型时提示“模型不存在,或不能用于本站的表单”或“审核流程不存在,或未在本站部署”。 模型须是本站或全局共享的表单模型;流程须在本站部署、类别为表单审核。
- 保存表单时提示“该状态的表单不可修改,需要“全部状态权限””。 类型有审核流程,表单已审核或审核中。需要角色开启全部状态权限,或由当前审核人在表单审核里修改。
- 批量通过时提示“任务“……”需要填写审核表单,不能批量通过,请逐个通过”。 该环节设置了必填的表单项,逐个点 通过 填写。
- 表单审核里显示“暂无待审核的表单”。 没有轮到自己审核的表单。没有设置审核流程的类型,表单不经过这里。
- 预览表单模板时提示“站点暂无可用于预览该模板的引用该模板的表单类型或其表单数据,请先创建后再预览”。 没有开启了前台可浏览的类型选用这个模板;详情模板还需要该类型至少有一条已审核的表单。