集成详细说明

1. 项目概述

2. 系统架构

3. 快速开始

4. 配置说明

5. API接口集成

6. 通信方式配置

7. 数据格式说明

8. 组件开发指南

9. 常见问题与解决方案

10. 附录

---

项目概述

1.1 简介

Ricon组态系统是一个基于Web的可视化组态编辑和监控平台，支持拖拽式画面编辑、实时数据监控、多种通信方式（WebSocket、MQTT、HTTP）以及丰富的组件库。

1.2 主要特性

• ✅ 可视化编辑 - 拖拽式组态画面编辑，所见即所得

• ✅ 实时监控 - 支持WebSocket、MQTT、HTTP三种实时数据通信方式

• ✅ 丰富组件 - 基础组件、图元组件、图表组件、装饰组件等

• ✅ 数据绑定 - 支持硬件设备数据点绑定和实时更新

• ✅ 响应式设计 - 支持多种屏幕尺寸和分辨率

• ✅ 场景管理 - 支持场景保存、加载、模板管理

• ✅ 权限控制 - 支持用户权限和token认证

1.3 技术栈

• 前端框架: Layui、Konva.js、ECharts

• 通信协议: WebSocket、MQTT、HTTP

• 数据格式: JSON

• 浏览器支持: Chrome、Edge、Firefox等现代浏览器

---

系统架构

2.1 目录结构

ricon/

1. ├── assets/ # 静态资源
2. │ ├── css/ # 样式文件
3. │ ├── images/ # 图片资源
4. │ ├── js/ # JavaScript文件
5. │ │ ├── common/ # 公共工具类
6. │ │ ├── core/ # 核心功能模块
7. │ │ │ ├── stageOperation.js # 场景操作核心
8. │ │ │ ├── stageView.js # 场景视图渲染
9. │ │ │ ├── webSocketClient.js # WebSocket客户端
10. │ │ │ ├── mqttClient.js # MQTT客户端
11. │ │ │ ├── httpClient.js # HTTP客户端
12. │ │ └── modules/ # 业务模块
13. │ │ ├── editor.js # 编辑器逻辑
14. │ │ └── view.js # 监控页面逻辑
15. │ └── json/ # 组件配置文件
16. ├── config/ # 配置文件
17. │ ├── apiClient.js # API客户端（核心配置文件）
18. │ ├── init.json # 系统初始化配置
19. │ └── 配置说明.md # 配置说明文档
20. ├── modules/ # 组件编辑模块
21. │ └── edit/ # 各类组件编辑页面
22. ├── pages/ # 功能页面
23. │ ├── config/ # 配置页面
24. │ ├── select/ # 选择页面
25. │ └── view/ # 视图页面
26. ├── editor.html # 编辑器页面
27. ├── view.html # 监控页面
28. └── README.md # 项目说明

2.2 核心模块说明

|-----------|-----------------------------------|--------------------------------------|
| 模块 | 文件 | 功能说明 |
| API客户端 | config/apiClient.js | 所有后台接口调用、系统配置管理 |
| 场景操作协调器 | assets/js/core/stageOperation.js | 场景操作核心协调器，所有功能已模块化拆分到 core/stage/ 目录 |
| 场景模块 | assets/js/core/stage/ | 场景操作功能模块化拆分（14个功能模块） |
| 场景视图 | assets/js/core/stageView.js | 场景渲染、数据更新、动画处理 |
| WebSocket | assets/js/core/webSocketClient.js | WebSocket连接和数据接收 |
| MQTT | assets/js/core/mqttClient.js | MQTT连接和消息订阅 |
| HTTP | assets/js/core/httpClient.js | HTTP轮询请求和数据获取 |
| 编辑器 | assets/js/modules/editor.js | 编辑器页面业务逻辑 |
| 监控页面 | assets/js/modules/view.js | 监控页面业务逻辑和通信初始化 |

---

快速开始

3.1 环境要求

• Web服务器: Nginx、Apache、IIS等

• 浏览器: Chrome、Edge、Firefox等现代浏览器（推荐Chrome）

• Node.js: 可选，用于开发调试

3.2 部署步骤

步骤1: 部署文件

将项目文件放置到Web服务器目录，例如：

• Nginx : /usr/share/nginx/html/ricon 或 D:/nginx/html/ricon

• Apache : /var/www/html/ricon

• IIS : C:\inetpub\wwwroot\ricon

步骤2: 配置Web服务器

Nginx配置示例：

代码块

server {

1. listen 80;
2. server_name localhost;
3. root /path/to/ricon;
4. index editor.html;
5. location / {
6. try_files $uri $uri/ /editor.html; }
7. # 支持跨域（如需要）
8. add_header Access-Control-Allow-Origin *;
9. add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
10. add_header Access-Control-Allow-Headers '
11. DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization'; }

步骤3: 配置系统参数

编辑 config/apiClient.js 文件，修改 SystemConfig 对象：

代码块

1. var SystemConfig = {
2. // HTTP服务地址
3. serviceIpPort: "http://your-server:90",
4. // WebSocket服务地址
5. webSocketUrl: "ws://your-server:8080/websocket/message",
6. // 接口路径前缀（可选） apiPrefix: "",
7. // 请求超时时间（毫秒） timeout: 30000 };

步骤4: 访问系统

• 编辑器 : http://localhost/ricon/editor.html?userId=xxx&token=xxx&stageId=xxx

• 监控页面 : http://localhost/ricon/view.html?userId=xxx&token=xxx&stageId=xxx

---

配置说明

4.1 系统配置（apiClient.js）

config/apiClient.js 是系统的核心配置文件，包含所有后台接口调用方法和系统配置。

4.1.1 SystemConfig配置对象

代码块

1. var SystemConfig = {
2. // HTTP服务地址
3. serviceIpPort: "http://www.byzt.net:90", // WebSocket服务地址 webSocketUrl: "ws://www.byzt.net:8080/websocket/message",
4. // 接口路径前缀（可选）
5. apiPrefix: "",
6. // 请求超时时间（毫秒） timeout: 30000 };

4.1.2 配置方法

方式1: 直接修改SystemConfig对象（推荐）

代码块

1. var SystemConfig = {
2. serviceIpPort: "http://your-server:90",
3. webSocketUrl: "ws://your-server:8080/websocket/message" };

方式2: 在代码中动态获取配置

代码块

1. // 获取服务地址
2. var serviceUrl = this.getServiceUrl('/api/path');
3. // 获取WebSocket地址 var wsUrl = this.getWebSocketUrl('/path');

4.2 系统初始化配置（init.json）

config/init.json 用于存储系统初始化配置，包括字体、分辨率、日期格式等。

主要配置项：

• saveCallbackFunction: 保存场景回调函数名

• editCallbackFunction: 编辑场景回调函数名

• clientViewbackFunction: 客户端查看回调函数名

• hardwareDataFunction: 硬件数据获取函数名

• fontText: 可用字体列表

• fontSize: 可用字体大小列表

• stageResolution: 场景分辨率选项

---

API接口集成

5.1 接口说明

所有API接口调用方法定义在 config/apiClient.js 文件的 ApiClient 类中。集成时需要实现以下接口：

5.2 场景保存接口

方法名 : saveStage

接口地址 : POST {serviceIpPort}/ztgl/hmgl/stageEdit

请求参数：

代码块

1. { stageDatajson: string,
2. // 场景JSON数据（字符串格式） dataKeyArray: string,
3. // 绑定的数据点编号（逗号分隔），如："a01,123,a02" stageBase64: string,
4. // 场景缩略图（Base64格式） stageId: string
5. // 场景ID（修改时必传，新建时不传） }

请求头：

代码块

1.Authorization: Bearer {token}

2.Content-Type: application/x-www-form-urlencoded

响应格式：

代码块

1. { code: 200,
2. data: 1,
3. // 1表示成功，0表示失败
4. message: "操作成功" }

实现示例：

代码块

1. saveStage: function (stageDatajson, dataKeyArray, stageBase64, UrlParam)
2. { $.ajax({
3. type: "POST", url: this.getServiceUrl('/ztgl/hmgl/stageEdit'),
4. data: { '
5. stageDatajson': stageDatajson,
6. 'dataKeyArray': dataKeyArray,
7. 'stageBase64': stageBase64,
8. 'stageId': UrlParam.stageId },
9. headers: { '
10. Authorization': 'Bearer ' + UrlParam.token },
11. success: function (data) { if (data.data == 1) { layer.msg('操作成功'); } else { layer.msg('操作失败'); } } }); }

5.3 场景编辑接口

方法名 : editStageData

接口地址 : GET/POST {serviceIpPort}/ztgl/hmgl/stageLoad

请求参数：

代码块

1. stageId: string
2. // 场景ID

响应格式：

代码块

1. { code: 200, data:
2. { stageDatajson: string,
3. // 场景JSON数据（字符串格式）
4. // ... 其他场景信息 } }

实现示例：

代码块

1. editStageData: function (UrlParam) { var stageJsons = "";
2. $.ajax({
3. type: "POST",
4. url: this.getServiceUrl('/ztgl/hmgl/stageLoad'),
5. data: { '
6. stageId': UrlParam.stageId },
7. headers: { 'Authorization': 'Bearer ' + UrlParam.token },
8. async: false, success: function (data)
9. { if (data && data.data && data.data.stageDatajson)
10. { stageJsons = data.data.stageDatajson; } } }); return stageJsons; }

5.4 场景查看接口

方法名 : viewStageData

接口地址 : GET/POST {serviceIpPort}/ztgl/hmgl/stageLoad

说明: 与编辑接口相同，但用于客户端查看场景。

5.5 硬件设备数据接口

5.5.1 获取项目列表

方法名 : getProjectList

接口地址 : GET/POST {serviceIpPort}/your-api/project

响应格式：

[ {code: "项目编号", name: "项目名称", type: "类型"}, ... ]

5.5.2 获取设备列表

方法名 : getDeviceList

接口地址 : GET/POST {serviceIpPort}/your-api/device

请求参数：

parentId: string // 项目ID type: string // 项目类型

响应格式：

[ {code: "设备编号", name: "设备名称", type: "类型"}, ... ]

5.5.3 获取从机列表

方法名 : getSlaveList

接口地址 : GET/POST {serviceIpPort}/your-api/slave

请求参数：

parentId: string // 设备ID type: string // 设备类型

5.5.4 获取传感器列表（数据点）

方法名 : getSensorList

接口地址 : GET/POST {serviceIpPort}/your-api/sensor

请求参数：

parentId: string // 从机ID type: string // 从机类型

响应格式：

[ {code: "传感器编号", name: "传感器名称", type: "类型"}, ... ]

5.6 用户模块管理接口

5.6.1 获取我的模块数据

方法名 : pictureList

接口地址 : GET/POST {serviceIpPort}/your-api/module

请求参数：

userId: string // 用户ID groupId: string // 分组ID（可选）

5.6.2 删除我的模块数据

方法名 : deletePictureById

接口地址 : DELETE/POST {serviceIpPort}/your-api/module/{moduleId}

请求参数：

moduleId: string // 模块ID

5.6.3 获取我的分组数据

方法名 : getMyGroupData

接口地址 : GET/POST {serviceIpPort}/your-api/group

请求参数：

userId: string // 用户ID

5.7 接口调用配置

在 config/init.json 中配置接口方法名映射：

代码

1. { "
2. saveCallbackFunction": "saveStage",
3. "editCallbackFunction": "editStageData",
4. "clientViewbackFunction": "viewStageData",
5. "hardwareDataFunction": "getHardwareData",
6. "initMyMoudleFunction": "pictureList",
7. "delteMyMoudleFunction": "deletePictureById",
8. "initMyGroupFunction": "getMyGroupData" }

---

通信方式配置

6.1 通信方式概述

系统支持三种实时数据通信方式：

• WebSocket - 实时双向通信，推荐用于高频数据更新

• MQTT - 基于发布/订阅的消息传输协议，适合IoT场景

• HTTP - 基于请求/响应的轮询通信，适合低频数据更新

6.2 WebSocket配置

6.2.1 服务器端配置

在 config/apiClient.js 中配置WebSocket服务器地址：

var SystemConfig = { webSocketUrl: "ws://your-server:8080/websocket/message" };

6.2.2 场景配置

在编辑器中选择"通信"标签页，配置WebSocket参数：

• WebSocket地址: WebSocket服务器完整URL

• 心跳间隔: 心跳包发送间隔（秒），默认10秒

• 自动重连: 是否在断开后自动重连

6.2.3 数据格式

服务器发送格式：

{ "MESSAGETYPE": "01", "MESSAGECONTENT": { "devicecode1": "value1", "devicecode2": "value2" } }

消息类型说明：

• "01" - 业务数据

• "02" - 提醒数据

• "03" - 网络诊断

• "04" - 命令发送后的提醒数据

• "05" - 心跳

6.3 MQTT配置

6.3.1 引入MQTT.js库

在 view.html 的 <head> 中添加：

<script src="https://unpkg.com/mqtt@4.3.7/dist/mqtt.min.js"></script>

或下载到本地：

<script src="assets/js/libs/mqtt/mqtt.min.js"></script>

6.3.2 场景配置

在编辑器中选择"通信"标签页，选择"MQTT"，配置参数：

• MQTT地址 : MQTT服务器WebSocket地址（如：ws://your-server:9001）

• 客户端ID : 唯一标识符（如：mqtt_client_123456）

• 用户名: MQTT认证用户名（可选）

• 密码: MQTT认证密码（可选）

• 订阅主题 : 要订阅的消息主题（如：/data/device）

• QoS等级: 消息质量等级（0-2）

QoS等级说明：

• 0 - 至多一次（可能丢失消息，但性能最好）

• 1 - 至少一次（可能重复消息，推荐）

• 2 - 仅一次（确保消息不丢失不重复，性能最低）

6.3.3 数据格式

MQTT消息格式：

{ "devicecode1": "value1", "devicecode2": "value2" }

6.4 HTTP配置

6.4.1 场景配置

在编辑器中选择"通信"标签页，选择"HTTP"，配置参数：

• HTTP地址 : 数据接口完整URL（如：`http://your-server:8080/api/data`）

• 请求方式: GET/POST/PUT/DELETE

• 轮询间隔: 请求间隔时间（秒），默认5秒

• 请求头 : JSON格式字符串（如：{"Content-Type": "application/json"}）

• 请求参数 : JSON格式字符串（如：{"key": "value"}）

6.4.2 数据格式

标准响应格式：

{ "code": 200, "data": { "devicecode1": "value1", "devicecode2": "value2" } }

直接数据格式：

{ "devicecode1": "value1", "devicecode2": "value2" }

6.5 通信配置保存

通信配置会随场景数据一起保存到服务器。在监控页面加载场景时，系统会自动根据配置的通信方式初始化相应的客户端。

配置存储位置：

• 存储在场景JSON的 stage.attrs.communicationConfig 中

• 保存场景时一并提交到服务器

---

数据格式说明

7.1 场景数据格式

场景数据以JSON字符串格式存储，包含以下主要信息：

• attrs: 场景属性（分辨率、背景、通信配置等）

• children: 场景中的组件列表

• class: 场景类型（Stage）

7.2 组件数据格式

每个组件包含：

• attrs: 组件属性（位置、大小、样式、数据绑定等）

• className: 组件类型

• children: 子组件列表

7.3 数据点绑定格式

组件通过 attrs.dataKey 属性绑定数据点：

dataKey: [ { key: "devicecode1", // 设备编号 name: "设备名称", // 显示名称 type: "number" // 数据类型 } ]

7.4 实时数据更新格式

实时数据以键值对形式更新，键名为设备编号（devicecode），值为设备当前值：

{ "devicecode1": 100, "devicecode2": "ON", "devicecode3": 25.5 }

7.5 URL参数格式

编辑器页面参数：

editor.html?userId={userId}&token={token}&stageId={stageId}

监控页面参数：

view.html?userId={userId}&token={token}&stageId={stageId}

参数说明：

• userId: 用户ID

• token: 认证令牌

• stageId: 场景ID（可选，新建场景时不传）

---

组件开发指南

8.1 组件类型

系统支持以下组件类型：

基础组件

• 文本组件 (Text) - 文本显示

• 按钮组件 (Button) - 可点击按钮

• 图片组件 (Image) - 图片显示和切换

• 日期组件 (CurrentDate) - 当前日期显示

• 天气组件 (Weather) - 天气信息显示

图表组件

• ECharts图表 (Echart) - 各种图表类型

• iframe图表 (IframeEchart) - 嵌入iframe图表

图元组件

• SVG组件 (SVG) - SVG图形

• 形状组件 (Shape) - 基本图形

• 电气图元 (Electric) - 工业电气图元

• 开关组件 (SwitchGear) - 开关图标

高级组件

• 表格组件 (Table) - 数据表格

• iframe组件 (Iframe) - 嵌入网页

• 视频组件 (Live) - 视频播放

• 动画组件 (Rotating, Pool) - 动画效果

8.2 添加新组件

步骤1: 创建编辑页面

在 modules/edit/ 目录创建：

• edit-xxx.html - 组件属性编辑界面

• editXxx.js - 组件编辑逻辑

步骤2: 注册组件

在 assets/json/basic.json 或相应配置文件中添加组件定义：

1. { "name": "组件名称",
2. "className": "组件类名",
3. "icon": "组件图标路径",
4. "defaultAttrs": { // 默认属性 },
5. "editPanel": [ // 属性面板配置 ] }

步骤3: 实现渲染逻辑

在 assets/js/core/stageOperation.js 中添加组件创建逻辑。 在 assets/js/core/stageView.js 中添加组件渲染和数据更新逻辑。

8.3 组件属性配置

组件属性采用JSON配置，支持以下属性类型：

|------------------|--------|------------------------------------------------|
| 类型 | 说明 | 示例 |
| input | 文本输入框 | {"type": "input", "label": "名称"} |
| color | 颜色选择器 | {"type": "color", "label": "颜色"} |
| selectAdvanced | 下拉选择框 | {"type": "selectAdvanced", "options": [...]} |
| slider | 滑块 | {"type": "slider", "min": 0, "max": 100} |
| hardwareInputNew | 硬件设备选择 | {"type": "hardwareInputNew"} |
| fontNew | 字体配置 | {"type": "fontNew"} |

---

常见问题与解决方案

9.1 配置问题

Q1: 修改配置后不生效？

解决方案：

1. 清除浏览器缓存（Ctrl+F5 / Cmd+Shift+R）

2. 检查配置文件路径是否正确

3. 查看浏览器控制台是否有JavaScript错误

Q2: 如何验证配置是否生效？

解决方案： 在浏览器控制台执行：

console.log(SystemConfig); console.log(initjson);

9.2 接口集成问题

Q1: 保存场景失败？

解决方案：

1. 检查 config/apiClient.js 中的 saveStage 方法

2. 确认接口地址和请求参数是否正确

3. 检查token是否有效

4. 查看浏览器控制台网络请求详情

Q2: 加载场景失败？

解决方案：

1. 检查 editStageData 或 viewStageData 方法

2. 确认stageId是否正确

3. 检查服务器返回数据格式是否符合要求

9.3 通信问题

Q1: WebSocket连接失败？

解决方案：

1. 检查WebSocket服务器地址是否正确

2. 确认服务器正在运行

3. 检查防火墙设置

4. 查看浏览器控制台的WebSocket错误信息

Q2: MQTT连接失败？

解决方案：

1. 确认MQTT.js库已正确引入

2. 检查MQTT服务器地址（需要使用WebSocket地址 ws://）

3. 验证用户名密码是否正确（如需要认证）

4. 检查订阅主题是否正确

Q3: HTTP请求失败？

解决方案：

1. 检查HTTP地址是否正确

2. 确认请求头和参数格式为有效的JSON

3. 检查服务器是否支持跨域请求（CORS）

4. 查看浏览器控制台的网络请求详情

9.4 数据更新问题

Q1: 数据不更新？

解决方案：

1. 检查通信连接状态

2. 确认数据点绑定是否正确

3. 验证数据格式是否符合要求

4. 查看浏览器控制台的数据接收日志

Q2: 数据格式错误？

解决方案：

1. 检查服务器返回的数据格式

2. 确认数据键名（devicecode）与绑定的数据点一致

3. 验证JSON格式是否正确

9.5 组件问题

Q1: 组件不显示？

解决方案：

1. 检查浏览器控制台是否有JavaScript错误

2. 确认相关库文件是否加载成功

3. 检查组件JSON配置是否正确

4. 验证Konva画布是否正常初始化

Q2: 组件数据绑定不生效？

解决方案：

1. 确认组件已正确绑定数据点

2. 检查数据点编号（key）是否正确

3. 验证实时数据是否包含对应的键名

---

附录

10.1 API方法列表

|---------------------|----------|----------------------------------------------------|
| 方法名 | 功能说明 | 参数 |
| saveStage | 保存场景数据 | stageDatajson, dataKeyArray, stageBase64, UrlParam |
| editStageData | 编辑场景数据 | UrlParam |
| viewStageData | 查看场景数据 | UrlParam |
| saveStageModuleData | 保存场景模板 | stageDatajson, UrlParam |
| pictureList | 获取我的模块数据 | UrlParam, groupId |
| deletePictureById | 删除我的模块数据 | UrlParam, moduleId |
| getMyGroupData | 获取我的分组数据 | UrlParam |
| getProjectList | 获取项目列表 | UrlParam |
| getDeviceList | 获取设备列表 | parentId, type, UrlParam |
| getSlaveList | 获取从机列表 | parentId, type, UrlParam |
| getSensorList | 获取传感器列表 | parentId, type, UrlParam |

10.2 配置文件说明

apiClient.js

• 位置 : config/apiClient.js

• 作用: API客户端，所有后台接口调用

• 主要配置: SystemConfig对象

init.json

• 位置 : config/init.json

• 作用: 系统初始化配置

• 主要配置: 字体、分辨率、函数名映射

10.3 重要全局变量

|--------------------|---------|----------|
| 变量名 | 类型 | 说明 |
| SystemConfig | Object | 系统配置对象 |
| ApiClient | Class | API客户端类 |
| initjson | Object | 初始化配置对象 |
| stageView | Object | 场景视图对象 |
| messageContentTemp | Object | 消息内容临时存储 |
| dataFlag | Boolean | 数据更新标志 |

10.4 技术文档

• Konva.js文档 : https://konvajs.org/

• ECharts文档 : https://echarts.apache.org/

• MQTT.js文档 : https://github.com/mqttjs/MQTT.js

• Layui文档 : https://layui.dev/

10.5 更新日志

2024-12

• ✨ 文件重命名：initConfig.js → apiClient.js

• ✨ 类名优化：InitConfig → ApiClient

• ✨ 新增通信配置功能，支持WebSocket、MQTT、HTTP三种方式

• ✨ 优化配置管理，将IP配置集中到 apiClient.js

• ✨ 实现MQTT和HTTP客户端代码

• ✨ 支持根据配置自动初始化相应的通信客户端

• ✨ 修复方法名拼写错误（Moudle → Module）

• ✨ 添加语义化方法名（getXm → getProjectList等）SA

技术文档

演示地址：http://1.15.10.177/