自定义页面 API 接入

本指南面向需要自行设计填写界面的站点维护者。你可以保留联系表单的服务端校验、附件、邮箱验证、开放时间、提交上限、通知和收件箱，自己负责页面与交互。

只需改变外观时，优先使用主题设置；只需放入自定义 HTML 区域时，使用嵌入代码即可。

获取当前表单的接入示例

1. 在设计器中选中字段，进入「高级字段设置 → API 字段名」，设置易懂且稳定的名称，例如 email、company。
2. 发布表单。
3. 进入「投放与分享 → 自定义页面接入」，点击「查看接入方式」。
4. 查看字段表，复制「当前表单的完整接入示例」和「字段契约」。
5. 将示例放在同一站点的页面中，把示例数据替换为访客输入，并将提交函数绑定到自己的提交按钮。

示例按当前已发布字段生成，按需包含附件上传和邮箱验证码流程，不会自动提交。表单结构或 API 字段名变化并重新发布后，应重新复制、核对示例。

无需访问插件源码，也不需要安装内部生成客户端。

区分几个名称

不要把这些名称互相替换。生成示例先通过稳定标识读取已发布表单，再使用返回的最新路径提交。

一次提交的流程

1. 读取已发布表单，保存当前的 revisionHash，记录开始填写时间。
2. 渲染字段并收集输入，按字段契约保留数值、布尔值、数组等实际类型。
3. 有文件时先创建上传任务并上传内容；有邮箱验证时先完成发送和验证。
4. 为本次提交生成 Idempotency-Key，连同版本、答案和验证结果一起发送。
5. 成功后读取回执编号，向访客显示完成结果；失败时按错误信息保留输入并提供修正入口。

同一次内容因网络异常重试，应复用原提交请求和 Idempotency-Key；修改答案后再创建新的提交尝试。提交期间禁用按钮，避免重复请求。

公开接口

以下路径均相对于当前 Halo 站点。{slug}、{name} 和 {uploadName} 是占位符，应替换为实际值并进行 URL 编码。

请求结构以后台生成示例与字段契约为准。附件内容使用 multipart/form-data；其他提交和验证请求使用 JSON。

附件、邮箱验证与续填

附件需要先上传，再将返回的附件信息放入答案。不能只传本机文件路径或任意公网文件地址。上传仍受字段类型、数量、大小和站点存储配置限制。

邮箱验证成功后，把验证结果用于最终提交；邮箱被修改后，需清除旧结果并重新发送、验证。验证码过期或发送频率受限时，应向访客展示重试方式。

只有开启跨设备继续填写后，才使用进度接口。应按表单设置获取访客同意，只保存允许的字段，保管好私密令牌并处理过期状态。保存进度不是正式提交，也不触发通知。完整示例主要演示正式提交，续填与其他自定义交互需自行接入。

权限与错误处理

同站点公开提交无需管理员令牌。关闭匿名填写后，仍需要访客的登录会话；同站点示例会携带当前会话。不要将管理员凭据、后台接口或长期密钥写入浏览器代码。

客户端校验用于改善体验，服务端仍会检查必填、格式、条件逻辑、开放时间、次数与容量限制。自定义页面也需要处理人机验证要求，复制示例不会自动接入第三方验证码界面。

跨站页面还需自行处理跨域、服务地址和登录会话，站内示例不能直接保证跨站可用。不要通过暴露管理员令牌解决公开填写问题。

上线验证

至少验证正常提交、必填失败、版本变化、重复点击和网络重试；有登录、附件、邮箱验证或续填时，分别验证对应流程。最后在收件箱确认答案与回执，并检查已启用方案的投递结果。

自定义页面仅调用提交接口不会自动获得完整的访问与字段行为分析；需要插件提供的完整填写体验和行为采集时，使用插件表单组件。

下一步

• 投放与分享
• 通知与集成
• 返回文档首页