|
| 1 | +# 自定义组件开发说明 |
| 2 | +## 前提条件 |
| 3 | +* 开发工具建议使用vscode， 基础安装要求建议node版本为18及以上, npm版本为10及以上。 |
| 4 | +* React组件建议使用antd组件库，模板默认版本为4.24.13。 |
| 5 | + |
| 6 | +## 操作步骤 |
| 7 | +### 约束条件 |
| 8 | +上传的组件包需要为zip压缩包，解压后大小不能超过5M，包含且只能包含三个部分： |
| 9 | +* 表单代码打包的静态资源文件 build文件夹。 |
| 10 | +* 表单的出入参配置文件 config.json。 |
| 11 | +* 表单的预览图 form.jpg/form.png/form.jpeg 大小不能超过1M。 |
| 12 | +## 开发组件代码 |
| 13 | +### 创建文件 |
| 14 | +* 用户在 /src/components文件夹下创建自己的组件文件，类型为.tsx。 |
| 15 | +### 表单获取流程数据 |
| 16 | +在流程中使用智能表单节点或结束节点选用表单时，可以将前序节点的输出作为表单初始化的数据使用。假设表单需要的数据结构为： |
| 17 | +``` |
| 18 | +{ |
| 19 | + "a": "你好", |
| 20 | + "b": "Demo1" |
| 21 | +} |
| 22 | +``` |
| 23 | +在表单里使用如下代码： |
| 24 | +data就是由流程传输给表单的，格式为{“a": "", "b": ""}的json数据，可以使用这个数据来初始化表单。 |
| 25 | + |
| 26 | +通信过程为： |
| 27 | +1. 智能表单监听 `message` 消息后，发送消息通知流程，智能表单已经启动，可以接收流程数据。 |
| 28 | +2. 流程接收到 `app-engine-form-ready` 消息后，发送流程数据给智能表单。 |
| 29 | + |
| 30 | +代码如下： |
| 31 | +```javascript |
| 32 | +window.addEventListener('message', handleMessage); |
| 33 | +window.parent.postMessage({ type: 'app-engine-form-ready', uniqueId }, '*'); |
| 34 | +``` |
| 35 | +注意：这里data的数据结构与config.json的入参配置一致。 |
| 36 | +``` |
| 37 | +const {data, terminateClick, resumingClick, restartClick} = useContext(DataContext); |
| 38 | +``` |
| 39 | +### 表单调用内置接口 |
| 40 | +平台提供了三个内置接口：继续对话（resumingClick），重新对话（restartClick），终止对话（terminateClick）。使用这几个内置接口，可以与流程进行交互。 |
| 41 | +在表单里使用如下代码，可以以调用方法的形式使用内置接口。 |
| 42 | +``` |
| 43 | +const {data, terminateClick, resumingClick, restartClick} = useContext(DataContext); |
| 44 | +``` |
| 45 | +1. 终止对话接口 |
| 46 | +终止对话接口适用于配置在**智能表单**节点的表单，适用于用户希望在流程的中间过程中，想要终止本地对话的场景。具体的过程是： |
| 47 | +``` |
| 48 | +应用流程进行到智能表单节点，流程暂停 ---> 用户与表单进行交互，触发终止对话接口 ---> 流程终止，对话结束 |
| 49 | +``` |
| 50 | +使用示例： |
| 51 | +``` |
| 52 | +如果表单里有按钮用于触发终止对话： |
| 53 | +<Button onClick={onTerminateClick}>终止对话</Button> |
| 54 | +
|
| 55 | +调用终止对话接口: |
| 56 | +const onTerminateClick = () => { |
| 57 | + terminateClick({content: //字符串，终止对话后希望显示的文本}); |
| 58 | +} |
| 59 | +如果希望点击终止对话后，显示的文本是"终止对话" |
| 60 | +terminateClick({content: "终止会话"}); |
| 61 | +``` |
| 62 | +**注意：在结束节点使用的表单如果调用终止对话接口，会出现错误。** |
| 63 | +2. 继续对话接口 |
| 64 | +继续对话接口适用于配置在**智能表单**节点的表单，适用于用户希望在流程的中间过程使用表单，进行一次人工交互，交互结束后流程继续的场景。具体的过程是： |
| 65 | +``` |
| 66 | +应用流程进行到智能表单节点，流程暂停 ---> 用户与表单进行交互，触发继续对话接口 ---> 流程继续进行到下一个节点 |
| 67 | +``` |
| 68 | +使用示例： |
| 69 | +``` |
| 70 | +如果表单里有按钮用于触发继续对话： |
| 71 | +<Button onClick={onResumeClick}>继续对话</Button> |
| 72 | +
|
| 73 | +调用继续对话接口: |
| 74 | +const onResumeClick = () => { |
| 75 | + resumingClick({params: //这里是表单的出参数据}); |
| 76 | +} |
| 77 | +如果表单的出参有两个，String 类型的"a"，Int 类型的"b": |
| 78 | +resumingClick({params: {a: "hello", b: 1}}); |
| 79 | +``` |
| 80 | +**注意：在结束节点使用的表单如果调用继续对话接口，会出现错误。** |
| 81 | +3. 重新对话接口 |
| 82 | + 重新对话接口适用于配置在**结束**节点的表单，适用于用户希望在流程结束后，想使用相同的问题重新再发起一次对话。具体的过程是： |
| 83 | +``` |
| 84 | +应用流程进行到结束节点，流程结束 ---> 表单展示流程输出，用户与表单进行交互，触发重新对话接口 ---> 再次从头发起一次流程 |
| 85 | +``` |
| 86 | +使用示例： |
| 87 | +``` |
| 88 | +如果表单里有按钮用于触发重新对话： |
| 89 | +<Button onClick={onRestartClick}>重新对话</Button> |
| 90 | +
|
| 91 | +调用重新对话接口: |
| 92 | +const onRestartClick = () => { |
| 93 | + restartClick({params: //这里是表单的出参数据}); |
| 94 | +} |
| 95 | +如果表单的出参有两个，String 类型的"a"，Int 类型的"b": |
| 96 | +restartClick({params: {a: "hello", b: 1}}); |
| 97 | +``` |
| 98 | +**注意：在智能表单节点使用的表单如果调用重新对话接口，需要先执行终止对话接口，将流程停止，再执行重新对话接口。** |
| 99 | +### 表单调用外部接口 |
| 100 | +* 如果想在表单中调用非平台内置的接口，需要保证接口支持跨域调用。 |
| 101 | +### 表单使用图片 |
| 102 | +* 表单使用图片文件时，需要将图片放置在/src/assets/images目录下 |
| 103 | +* 表单路径需要写为"./src/assets/images/图片文件名 |
| 104 | +示例： |
| 105 | +``` |
| 106 | +<img src="./src/assets/images/empty.png" alt="" height="100px" width="100px"/> |
| 107 | +``` |
| 108 | +### 表单添加样式文件 |
| 109 | +* 可以在/src/styles目录下添加样式文件，请使用.scss类型 |
| 110 | +### 调试表单 |
| 111 | +``` |
| 112 | +执行 npm install |
| 113 | +执行 npm start |
| 114 | +启动表单项目，可以查看是否符合预期 |
| 115 | +``` |
| 116 | +### 打包表单代码 |
| 117 | +``` |
| 118 | +执行 npm run build 将组件打包在build文件夹里 |
| 119 | +``` |
| 120 | +## 表单出入参配置 |
| 121 | +* 表单的出入参配置需要为json文件，名称为config.json。 |
| 122 | +* 文件内容表示表单的出入参的类型、描述以及参数顺序等信息，需要符合[json schema规范](https://json-schema.apifox.cn/)。 |
| 123 | +### 约束 |
| 124 | +* 最外层parameters字段是入参，入参第一层必须type为object。 |
| 125 | +* 必须包含name，支持中文、英文、数字、空格、中划线、下划线组合。 |
| 126 | +* 可以包含description, 对参数进行描述。 |
| 127 | +* 必须包含parameters。 |
| 128 | +* 必须包含required, 内容不可以为properties下参数名之外的参数名。 |
| 129 | +* 可以包含order, 若写必须为properties下所有参数名的列表；若不写，则默认按照properties下所有参数名的顺序。 |
| 130 | +* 必须包含return，return字段是出参。 |
| 131 | +### 示例 |
| 132 | +``` |
| 133 | +// 这是一个表单的出入参都为 字段名："a", 类型：String; |
| 134 | +{ |
| 135 | + "schema": { |
| 136 | + "parameters": { |
| 137 | + "type": "object", |
| 138 | + "required": [ |
| 139 | + "a", |
| 140 | + "b" |
| 141 | + ], |
| 142 | + "properties": { |
| 143 | + "a": { |
| 144 | + "type": "string", |
| 145 | + "default": "" |
| 146 | + }, |
| 147 | + "b": { |
| 148 | + "type": "string", |
| 149 | + "default": "" |
| 150 | + } |
| 151 | + } |
| 152 | + }, |
| 153 | + "return": { |
| 154 | + "type": "object", |
| 155 | + "properties": { |
| 156 | + "a": { |
| 157 | + "type": "string" |
| 158 | + }, |
| 159 | + "b": { |
| 160 | + "type": "string" |
| 161 | + } |
| 162 | + } |
| 163 | + } |
| 164 | + } |
| 165 | +} |
| 166 | +``` |
| 167 | +## 表单预览图 |
| 168 | +* 表单预览图的类型支持为.jpg/.png/.jpeg, 名称为form，大小不超过1M。 |
| 169 | +## 打包 |
| 170 | +* 将build文件夹、config.json、form.png打成zip压缩包，压缩包名称支持大小写英文、中文和数字的字符串,可以包含中划线(-)和下划线(_),但不能以中划线(-)和下划线(_)开头或结尾。 |
0 commit comments