自定义表单使用说明
自定义表单使用说明
以思威控站点的联系我们表单为例
本文面向站点管理员和运营人员，介绍如何在 ChestnutCMS 中配置自定义表单、将表单展示在网站页面中，以及查看和维护访客提交的数据。完成配置后，应从前台提交一条测试记录，再到后台核对结果。
1 认识思威控示例表单
自定义表单用于收集访客填写的信息。思威控示例通过姓名、联系电话、邮箱和公司名称等字段收集联系资料，方便后续沟通。表单配置决定收集哪些数据，网站模板决定这些字段在前台如何展示和提交。
示例配置对照
| 项目 | 思威控示例 |
|---|---|
| 所属站点 | 思威控 |
| 表单编码 | contactus |
| 表单名称 | 示例初始化数据中为 xx，识别表单时以编码 contactus 为准 |
| 数据表 | cms_cfd_default |
| PC 表单模板 | customform.template.html |
| 联系我们页面模板 | contactus.template.html |
| 需要验证码 | 开启 |
| 需要登录 | 关闭 |
表单名称用于后台识别，可按业务需要设置为“联系我们”等清晰名称。表单编码用于模板引用，应保持稳定。验证码、登录要求和提交限制应在当前后台中核对后使用。
进入已有表单
- 登录管理后台，在站点选择处切换到“思威控”。
- 进入 互动运营 → 自定义表单。
- 在列表的“编码”列找到
contactus。列表支持按表单名称和状态查询；名称搜索框用于搜索名称。 - 需要查看提交记录时，点击表单名称或行内的数据列表入口；需要维护配置时，点击 编辑 或字段管理入口。
若该表单已经存在，可直接检查字段、模板和提交效果。新建同类表单时，再按照第 2 节操作，使用不同的表单编码。
2 新建表单并设置提交规则
填写基本信息
在自定义表单列表点击 新增，填写以下内容后点击 提交。
| 配置项 | 填写方法 |
|---|---|
| 表单名称 | 使用便于识别的名称，例如“联系我们” |
| 表单编码 | 示例为 contactus；同一站点新建其他表单时使用独立编码，例如 contactus_test |
| 数据表 | 从下拉框选择 cms_cfd_default；特殊数据表由技术维护人员准备 |
| 需要验证码 | 对照思威控示例开启，并确认前台模板已接入验证码 |
| 需要登录 | 对照思威控示例关闭，允许未登录访客填写；仅面向会员时再开启 |
| 提交限制 | 根据下一节说明选择限制规则 |
| 备注 | 记录表单用途，例如“用于收集网站访客联系资料” |
表单编码支持字母、数字和下划线，最长 50 个字符；表单名称最长 100 个字符。数据表只在新建时选择，编辑窗口不提供更换数据表的入口。
选择提交限制
| 规则 | 实际作用 | 使用时注意 |
|---|---|---|
| 无限制 | 不按 IP 或访客标识阻止重复提交 | 仍需满足已配置的登录、验证码和字段校验要求 |
| IP | 同一表单中，已有相同 IP 的提交记录时拒绝再次提交 | 同一单位或网络中的多位访客可能共用出口 IP |
| 浏览器指纹 | 同一表单中，已有相同访客标识的记录时拒绝再次提交 | 依赖前台传递标识；登录时可使用会员标识 |
这两种去重规则按已有记录判断，不能理解为“每天限提交一次”。允许客户后续再次咨询的业务，可选择“无限制”并保留验证码；是否限制重复提交由实际业务决定。
新增成功后，表单状态为 草稿。接下来配置字段，再次进入 编辑 选择模板，最后发布并验证。
3 配置需要收集的字段
思威控字段示例
在 contactus 所在行点击字段管理入口，查看或配置以下字段。
| 字段名称 | 字段编码 | 数据类型 | 表单控件 |
|---|---|---|---|
| 姓名 | uname | 短文本 | 单行输入框 |
| 联系电话 | phone | 短文本 | 单行输入框 |
| 邮箱 | 短文本 | 单行输入框 | |
| 公司名称 | company | 短文本 | 单行输入框 |
字段编码是前台提交数据时使用的名称。例如，姓名字段提交的是 uname，不能在模板中随意改成 name。联系电话使用文本存储，便于保留号码前的 0、区号或其他业务需要的格式。
新增或编辑一个字段
- 点击 新增；维护已有字段时，点击该行 编辑。
- 填写字段名称和编码，例如“姓名”和
uname。 - 使用默认数据表时选择数据类型，如“短文本”；使用自定义数据表时选择对应的映射字段。
- 选择表单控件，例如单行输入框。需要多行内容时选择多行输入框，并使用能容纳相应内容的数据类型。
- 按业务需要设置校验、默认值、排序和备注，点击 确定 保存。
- 回到列表核对字段。采用固定 HTML 的前台模板，还需要同步调整输入项及排列顺序。
设置校验和扩展字段
可通过“非空”校验要求访客必须填写，通过“邮箱”校验检查邮箱格式。联系电话是否采用“手机号码”校验，应先确认是否允许固定电话、分机或境外号码。
建议按业务确认姓名、联系电话、邮箱哪些必须填写，公司名称可按需设为选填。这些是配置建议，实际要求以字段中保存的校验规则为准，并应同步到前台提示。
若需要增加“咨询内容”，可新增字段 message，使用多行输入框及合适的文本类型，再请模板维护人员同步增加前台输入项。该字段属于扩展示例，不属于上述四个原始示例字段。
已有正式数据后，修改字段编码、类型、映射或删除字段前，应评估历史数据和前台模板的影响。
4 配置模板并发布到前台
为表单选择模板
- 回到自定义表单列表，点击
contactus所在行的 编辑。 - 在 PC 发布通道对应的模板项中，点击文件夹按钮，选择
customform.template.html。 - 其他发布通道按需要配置对应模板，然后点击 提交 保存。
模板项在表单创建成功后的编辑窗口中显示。 新增窗口中没有模板项时，先保存，再进入编辑即可。
确认联系我们页面已引用表单
表单模板负责输入框和提交行为；联系我们页面模板负责网站页面布局。在思威控示例中，两个文件分别为 customform.template.html 和 contactus.template.html。
由模板维护人员确认联系我们页面在适当位置引用编码为 contactus 的表单。可使用以下模板标签：
<@cms_custom_form code="contactus" />
模板需同时匹配 uname、phone、email、company 四个字段编码。新增后台字段后，固定 HTML 模板中的前台输入框需要同步添加。
发布并核对效果
- 返回自定义表单列表，点击该行 发布，确认状态显示为 已发布。
- 重新发布使用该表单的“联系我们”页面；页面模板也有修改时，一并重新发布受影响的页面。
- 打开思威控网站的“联系我们”入口，检查字段、验证码和提交按钮是否完整。
- 如果页面仍是旧内容，先核对当前站点、发布通道和模板，再检查发布任务及页面缓存。
点击发布后，还应以实际页面显示和提交结果确认是否生效。仅看到“已发布”状态，不能替代前台验证。
5 从前台完成一次提交验证
正常提交
- 打开思威控网站的“联系我们”页面，检查输入项是否与后台字段一致。
- 填写容易识别的测试资料，例如姓名“表单测试”、公司名称“测试公司”、邮箱
form-test@example.com。电话使用获准用于测试且符合当前校验规则的号码。 - 如启用验证码，按页面提示完成验证；如启用登录要求，使用已登录的网站会员账号操作。
- 点击提交，确认页面出现成功提示。具体提示文字由前台模板决定。
- 回到后台的数据列表，找到刚才的测试记录，逐项核对填写内容。
同时检查异常情况
| 验证项目 | 操作方法 | 预期检查点 |
|---|---|---|
| 必填校验 | 留空已设置非空校验的字段后提交 | 提示补填，后台不增加成功记录 |
| 格式校验 | 为已设置邮箱校验的字段输入错误格式 | 提示格式错误，修正后可继续提交 |
| 验证码 | 不完成验证码或使用无效验证结果提交 | 提示验证失败，重新验证后再提交 |
| 重复提交 | 在测试环境按所选规则再次提交 | IP 或浏览器指纹规则应阻止对应的重复记录 |
| 前后台一致 | 查看刚提交的记录 | 姓名、电话、邮箱、公司名称与输入内容一致 |
测试应覆盖实际使用的发布通道。后台手工新增记录适用于补录，不能替代前台提交、验证码和重复提交规则的验证。
6 查看和维护提交数据
打开数据列表
在自定义表单列表中，点击 contactus 对应的表单名称或数据列表入口，即可查看该表单收到的数据。列表按字段展示内容，也可展示 IP、UUID、创建时间等系统字段。
查询和查看记录
在 IP 查询框输入完整 IP 地址后点击 搜索；点击 重置 清除条件。记录较多时，使用底部分页查看。该页面当前提供 IP 查询，不应把此输入框当作姓名或电话搜索框。
需要查看某条记录的完整可编辑内容时，点击该行 编辑。仅查看时，检查完点击 取消；需要修正内容时，再点击 提交 保存。
手工补录和修正
- 手工补录：点击数据列表中的 新增，填写各字段后点击 提交，用于录入通过电话等其他渠道收到的资料。
- 修正内容：点击记录行的 编辑，核对并修改字段后点击 提交。补录或修正前，应确认信息来源，避免覆盖客户原始表达。
删除记录
单条删除可使用记录行的 删除 按钮；批量删除可先勾选记录，再点击顶部 删除。在确认窗口中再次核对范围，仅清理明确不需要保留的测试或无效记录。
当前数据列表提供新增、编辑、删除和 IP 查询，没有独立的数据导出、审核或回复按钮。需要备份、导出或跟进记录时，应使用团队已有的管理方式，或交由管理员处理。
7 日常维护和问题处理
修改后如何生效
修改表单配置后点击 提交 保存。涉及字段、模板或前台展示时，同步检查模板，重新发布表单及使用它的页面，再做一次前台提交验证。调整必填或格式校验后，也要检查前台提示是否与后台规则一致。
下线和删除
暂停展示时，对已发布表单点击 下线，确认状态变为 已下线，并检查联系我们页面是否已移除表单。恢复使用时，检查配置后重新发布。
下线会移除生成的表单静态片段。若业务要求完全停止收集，应由技术维护人员同时确认页面入口和提交接口的停用效果。
删除表单前，应先备份需要保留的数据、解除页面模板引用，并确认已不再使用。删除表单与删除某条提交记录是两种操作；临时停用优先使用下线。
常见问题
| 现象 | 检查方法 |
|---|---|
| 找不到 contactus | 确认当前站点为思威控，清除名称和状态筛选，再查看编码列 |
| 新增时没有模板项 | 先保存表单，再进入编辑窗口选择发布通道模板 |
| 后台已加字段，前台未出现 | 检查模板是否增加对应输入项，编码是否一致，并重新发布页面 |
| 显示已发布，前台没有表单 | 检查页面引用的编码、对应通道模板、发布任务及页面缓存 |
| 提示请先登录 | 检查“需要登录”是否开启；后台登录不等于网站会员登录 |
| 提示请勿重复提交 | 检查 IP 或浏览器指纹规则及已有记录，确认是否符合业务要求 |
| 提示 UUID 参数不能为空 | 交由模板维护人员检查访客标识的生成与传递 |
| 提交成功却找不到记录 | 确认同一站点、同一表单，清除 IP 筛选并刷新列表 |
| 数据字段为空或错位 | 核对前台提交字段编码与后台字段编码，尤其是 uname 等示例字段 |
交给模板维护人员的核对项
- 页面引用的表单编码为
contactus，表单模板配置在正确的发布通道下。 - 表单模板使用当前表单的
CustomForm.formId，提交地址可取CustomForm.action。 - 提交数据使用
uname、phone、email、company等后台字段编码，并包含formId。 - 前台提交接口为
POST /api/customform/submit，接收 JSON；接口根地址以站点配置为准。 - 前台需传递访客标识，当前支持通过请求头或请求参数传递
cc-uuid。开启验证码时，需与验证码流程使用相同标识。 - 验证码获取入口为
GET /api/customform/captcha，需要formId；验证码提交数据应沿用站点已接入的组件格式。 - 使用 SSI 嵌入时，确认服务器支持 SSI；模板或表单变更后核对实际生成页面，不仅检查后台状态。
