企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 低代码
• 后端
• 前端
• 流程编排
• RAG

智能表单是 AppPlatform 大模型应用工作流中连接流程与用户的关键交互载体：在流程运行到智能表单节点或结束节点时，应用会将前序节点的输出作为表单初始化数据，并通过表单收集用户输入回传给流程。本文以仓库内 原生 html 模板 为骨架，完整讲解如何从零开发一个可上传、可运行、可调试的原生 HTML 自定义表单组件，包括包结构约束、流程数据通信协议、三个内置对话接口的调用方式、config.json 出入参配置规范，以及打包上传的全过程，并结合 render.tsx 与 upload-form.tsx 等前端源码，揭示平台侧的校验与通信实现原理。

上图是仓库中 原生 html 模板 自带的预览图（form.png），展示了一个包含文本输入框、下拉选择框与"继续对话 / 重新对话 / 终止对话"三个按钮的典型表单界面，读者完成本文的实战练习后即可产出类似效果的表单组件。

模板目录结构与三个必选部件

原生 HTML 模板是三类官方模板（React 模板、Vue 模板、原生 HTML 模板）中最轻量的一种，无需 Node 环境即可直接开发和调试。其完整目录结构如下（见 examples/template/原生html模板）：

原生html模板/ ├── README.md # 开发说明（本文主题文档） ├── config.json # 表单出入参配置（JSON Schema） ├── form.png # 表单预览图（1657x359） ├── index.html # 表单页面骨架 ├── index.js # 表单逻辑与平台通信代码 ├── assets/ │ ├── images/empty.png # 表单内使用的图片示例 │ └── styles/reset.css # 样式文件示例 └── css/ ├── bootstrap.min.css # 引用的第三方样式库 └── form.css # 表单自定义样式

前提条件

• 开发工具建议使用 VSCode，方便直接打开index.html调试和编辑 JS 代码；
• 原生 HTML 模板不依赖 Node/npm（与 React 模板要求 Node 18+、npm 10+ 不同），浏览器即可完成大部分调试工作。

约束条件（上传包的硬性规范）

上传的组件包必须为zip 压缩包，解压后大小不能超过 5M，且包内包含且只能包含三个部分：

平台侧会对这些约束进行实际校验。在 upload-form.tsx 中可以看到，上传时会用 JSZip 解压并依次检查：

• 必需文件：config.json、build/index.js、build/index.html（见 upload-form.tsx）；
• 预览图文件：form.png/form.jpg/form.jpeg三者至少存在其一（见 upload-form.tsx）；
• 预览图大小校验：uncompressedSize / 1024 > 1024（即大于 1M）时拒绝上传（见 upload-form.tsx）；
• 总大小校验：解压后所有文件总大小超过1024 * 5（即 5M）时拒绝上传（见 upload-form.tsx）。

因此开发阶段就要注意：build 产物尽量精简，图片资源控制在合理体积内，避免上传时被拦截。

开发组件代码

创建文件

在模板根目录下建立 HTML 文件即可，模板默认的入口文件为index.html。参照 index.html，页面骨架由表单控件与三个操作按钮组成，并在</body>前通过<script src="./index.js"></script>引入逻辑脚本：

<div id="element"> <form> <div class="form-row"> <div class="form-group col-md-6"> <label>a</label> <input id="inputA" type="text" class="form-control"> </div> <div class="form-group col-md-6"> <label>b</label> <select id="selectB"> <option value="demo1">Demo1</option> <option value="demo2">Demo2</option> </select> </div> <button class="btn btn-primary resuming">继续对话</button> <button class="btn btn-primary reStart">重新对话</button> <button class="btn btn-primary terminate">终止对话</button> </div> </form> </div>

模板的 CSS 使用 Bootstrap（css/bootstrap.min.css）配合自定义样式（css/form.css），其中 form.css 定义了#element内边距、.form-group布局与按钮间距等基础样式。

表单获取流程数据：双阶段 message 通信协议

在流程中使用智能表单节点或结束节点选用表单时，可以将前序节点的输出作为表单初始化的数据使用。假设表单需要的数据结构为：

{ "a": "你好", "b": "Demo1" }

表单通过window.addEventListener('message', handleMessage)监听来自流程的数据，data就是由流程传输给表单的 JSON 数据（格式为{"a": "", "b": ""}），可直接用于初始化表单。注意：receiveData 的数据结构与 config.json 的入参配置必须一致。

通信过程分为两步：

1. 智能表单启动后，监听message消息，同时发送消息通知流程——表单已经启动，可以接收流程数据；
2. 流程接收到app-engine-form-ready消息后，将流程数据发送给智能表单。

对应代码如下（详见 index.js）：

document.addEventListener("DOMContentLoaded", function () { const handleMessage = (event) => { receiveData = event.data; initializeFormData(receiveData.data); window.removeEventListener("message", handleMessage); }; window.addEventListener("message", handleMessage); window.parent.postMessage({ type: 'app-engine-form-ready', uniqueId }, '*'); // ... });

其中uniqueId是从当前页面 URL 中解析出来的表单实例标识，模板通过正则/uniqueId=([a-zA-Z0-9-]+)/从window.location.href中提取（见 index.js），它是后续所有消息通信的会话凭证，请勿修改或删除该范围内的代码。

从平台侧看，这段协议由 render.tsx 实现：表单以 iframe 形式加载（sandbox="allow-scripts"，src 指向${origin}/.../static/${path}?uniqueId=${props.uniqueId}），当收到app-engine-form-ready消息后，通过handleIframeLoad将uniqueId、origin、tenantId和流程数据data一并通过postMessage回传给表单（见 render.tsx），iframe 的高度也由表单通过app-engine-form-resize消息动态上报（见 render.tsx）。

表单调用内置接口：三大对话交互方法

平台提供了三个内置接口，表单可以"以调用方法的形式"与流程进行交互：

• 继续对话（resumingClick）
• 重新对话（restartClick）
• 终止对话（terminateClick）

这三个方法本质上是向父窗口发送特定 type 的 postMessage 消息（见 index.js）：

// 终止会话 const terminateClick = (params) => { window.parent.postMessage( { type: "app-engine-form-terminate", ...params, uniqueId }, receiveData.origin ); }; // 继续会话 const resumingClick = (params) => { window.parent.postMessage( { type: "app-engine-form-resuming", ...params, uniqueId }, receiveData.origin ); }; // 重新生成 const reStartClick = (params) => { window.parent.postMessage( { type: "app-engine-form-restart", ...params, uniqueId }, receiveData.origin ); };

平台侧在 render.tsx 中监听这四种消息类型，分别路由到终止会话、继续会话、重新会话以及 iframe 高度调整逻辑。

1. 终止对话接口（terminateClick）

适用场景：配置在智能表单节点的表单，用于用户在流程中间过程中想要终止本地对话。

过程：

应用流程进行到智能表单节点，流程暂停 ---> 用户与表单进行交互，触发终止对话接口 ---> 流程终止，对话结束

使用示例（表单内放置触发按钮，并绑定终止对话接口）：

<button class="btn btn-primary terminate">终止对话</button>

document.querySelector('.terminate').addEventListener('click', (event) => { event.preventDefault(); terminateClick({ content: '终止会话' }); });

content是终止对话后希望显示的文本，例如terminateClick({ content: "终止会话" })会显示"终止会话"。平台侧收到app-engine-form-terminate后会调用stopInstance/guestModeStopInstance终止实例（见 render.tsx）。

注意：在结束节点使用的表单如果调用终止对话接口，会出现错误。

2. 继续对话接口（resumingClick）

适用场景：配置在智能表单节点的表单，用于流程中间过程进行一次人工交互，交互结束后流程继续。

过程：

应用流程进行到智能表单节点，流程暂停 ---> 用户与表单进行交互，触发继续对话接口 ---> 流程继续进行到下一个节点

使用示例：

<button type="submit" class="btn btn-primary resuming">继续对话</button>

document.querySelector('.resuming').addEventListener('click', (event) => { event.preventDefault(); resumingClick({ params: getFormData() }); });

如果表单的出参有两个，String 类型的"a"、Int 类型的"b"，则传参写法为：

resumingClick({ params: { a: "hello", b: 1 } });

params即表单的出参数据。平台侧收到app-engine-form-resuming后，会把params序列化进formData与businessData.output，调用saveContent/guestModeResumeChat让流程继续（见 render.tsx）。

注意：在结束节点使用的表单如果调用继续对话接口，会出现错误。

3. 重新对话接口（restartClick）

适用场景：配置在结束节点的表单，用于流程结束后，用户希望使用相同的问题重新发起一次对话。

过程：

应用流程进行到结束节点，流程结束 ---> 表单展示流程输出，用户与表单进行交互，触发重新对话接口 ---> 再次从头发起一次流程

使用示例：

<button type="submit" class="btn btn-primary reStart">重新对话</button>

document.querySelector('.reStart').addEventListener('click', (event) => { event.preventDefault(); reStartClick({ params: getFormData() }); });

如果表单的出参有两个，String 类型的"a"、Int 类型的"b"，则传参写法为：

restartClick({ params: { a: "hello", b: 1 } });

平台侧收到app-engine-form-restart后，将params作为output调用saveChart/guestModeRestartChat重新发起流程（见 render.tsx）。

注意：在智能表单节点使用的表单如果调用重新对话接口，需要先执行终止对话接口，将流程停止，再执行重新对话接口。

三个接口的适用范围总结如下：

表单调用外部接口

如果想在表单中调用非平台内置的接口（如第三方业务系统 API），需要保证接口支持跨域调用（CORS），否则浏览器会拦截请求。

表单使用图片

• 表单使用图片文件时，需要将图片放置在/assets/images目录下（模板中已有示例 assets/images/empty.png）；
• 表单路径需要写为./assets/images/图片文件名。

示例：

<img src="./assets/images/empty.png" alt="">

表单添加样式文件

可以在/src/styles目录下添加样式文件，原生 HTML 模板请使用.css类型。模板默认在index.html的<head>中通过<link>引入样式（见 index.html）：

<link rel="stylesheet" href="./assets/styles/reset.css"> <link rel="stylesheet" href="./css/bootstrap.min.css"> <link rel="stylesheet" href="./css/form.css">

调试表单

原生 HTML 模板的调试非常轻量：在浏览器中直接打开index.html，查看页面是否符合预期即可。由于表单的核心交互（流程数据下发、三个内置接口）依赖平台父窗口环境，本地调试主要验证的是表单 UI 渲染、样式与基础 JS 逻辑；完整联调需将表单作为智能表单节点/结束节点挂载到流程中运行。

打包表单代码

新建build文件夹，将表单文件index.html、index.js、assets文件夹、css文件夹放置在build文件夹中。最终build目录结构与平台校验逻辑（要求存在build/index.js与build/index.html）对齐：

build/ ├── index.html ├── index.js ├── assets/ │ ├── images/ │ └── styles/ └── css/

表单出入参配置（config.json）

表单的出入参配置需要为 JSON 文件，名称为config.json，文件内容表示表单出入参的类型、描述以及参数顺序等信息，需要符合 JSON Schema 规范。

配置约束

• 最外层parameters字段是入参，入参第一层必须type为object；
• 必须包含name，支持中文、英文、数字、空格、中划线、下划线组合；
• 可以包含description，对参数进行描述；
• 必须包含parameters；
• 必须包含required，内容不可以为properties下参数名之外的参数名；
• 可以包含order，若写则必须为properties下所有参数名的列表；若不写，默认按照properties下所有参数名的顺序；
• 必须包含return，return字段是出参。

完整示例

仓库模板的 config.json 与文档中的示例一致，是一个出入参都为字段名"a"、"b"、类型均为 String 的完整配置：

{ "schema": { "parameters": { "type": "object", "required": [ "a", "b" ], "properties": { "a": { "type": "string", "default": "" }, "b": { "type": "string", "default": "" } } }, "return": { "type": "object", "properties": { "a": { "type": "string" }, "b": { "type": "string" } } } } }

对照模板实现可以更直观地理解该配置的用途：

• parameters中a、b的default值对应表单初始化数据{"a": "", "b": ""}，在 index.js 中通过initializeFormData将data.a、data.b写入#inputA输入框与#selectB下拉框；
• return中的出参结构对应 index.js 的getFormData()，继续对话 / 重新对话时以{ params: getFormData() }的形式回传。

若入参包含order字段，则可显式指定参数展示顺序，例如"order": ["b", "a"]会先展示b再展示a；不写时按properties中定义顺序排列。

表单预览图

• 表单预览图的类型支持.jpg/.png/.jpeg，名称为form（即form.png/form.jpg/form.jpeg）；
• 大小不超过 1M。

预览图用于在智能表单节点 / 结束节点选用表单时展示表单样式，平台侧在上传时即校验其体积（见 upload-form.tsx），因此建议在上传前将截图压缩至 1M 以内。

打包与命名规范

将build文件夹、config.json、form.png打成zip 压缩包，压缩包名称需遵守以下规则：

• 支持大小写英文、中文和数字的字符串；
• 可以包含中划线（-）和下划线（_）；
• 但不能以中划线（-）和下划线（_）开头或结尾。

平台侧对应使用正则^[a-zA-Z0-9\u4e00-\u9fa5]+([_-][a-zA-Z0-9\u4e00-\u9fa5]+)*$校验压缩包文件名，并限定文件类型必须为zip、大小不超过 5M（见 upload-form.tsx）。

打包完成后，即可在智能表单节点或结束节点的表单选择器中上传该 zip 包，平台会将build下的静态资源发布到静态服务，并通过 iframe 加载渲染（对应 render.tsx 中的src拼接逻辑）。

开发速查清单

完成一个可用的原生 HTML 智能表单组件，按以下顺序执行即可：

1. 搭建页面：在根目录创建index.html，编写表单 UI（输入框、下拉框、按钮等）；
2. 编写通信代码：在index.js中保留"请勿修改或删除"范围内的代码（message监听、app-engine-form-ready发送、uniqueId解析、ResizeObserver高度上报），并实现initializeFormData、getFormData及三个接口回调；
3. 配置出入参：编写config.json，确保parameters/return结构与表单实际数据一致；
4. 准备资源：图片放assets/images，样式文件放assets/styles（.css 类型）；
5. 本地调试：浏览器直接打开index.html检查 UI 与逻辑是否符合预期；
6. 打包上传：新建build文件夹放入index.html、index.js、assets、css，与config.json、form.png（不超过 1M）打成 zip（解压后不超 5M，文件名符合命名规则）上传。

遵循以上流程与平台侧校验逻辑（上传校验见 upload-form.tsx、运行时渲染与消息路由见 render.tsx），即可在 AppPlatform 流程中以智能表单节点或结束节点接入自定义的原生 HTML 表单，实现流程数据注入、人工交互、对话继续 / 终止 / 重新发起等完整能力。若需要组件化更强的方案，可参考仓库内的 React 模板 与 Vue 模板 及其在 frontend/src/pages/intelligent-form/components/form-demos 中的 React 实现示例（如 smart-form/src/app.tsx，其消息协议与本文完全一致，仅将原生 API 封装进DataContext提供data、terminateClick、resumingClick、restartClick）。

• 人工智能
• 大模型
• AI 应用
• 低代码
• 后端
• 前端
• 流程编排
• RAG