Ricon组态系统集成说明书

一、概述

1.1 系统简介

Ricon组态系统是一款基于Web技术开发的可视化组态编辑和监控系统，支持拖拽式组件编辑、多种通信协议接入、实时数据展示等功能。系统采用模块化架构设计，易于与第三方系统集成。

1.2 核心特性

特性	说明
可视化编辑器	支持拖拽组件、配置属性、实时预览
多协议支持	WebSocket、MQTT、HTTP三种通信方式
丰富组件库	基础组件、图表组件、装饰组件、行业组件
ECharts集成	支持仪表盘、折线图、柱状图、散点图、雷达图等20+种图表
模块化架构	核心模块解耦，便于扩展和集成
实时数据更新	支持数据实时推送和图表动态更新
模板管理	支持场景保存为模板，便于复用
导入导出	支持场景数据的导入和导出
响应式设计	支持多种分辨率画布配置

1.3 技术栈

技术	版本	用途
jQuery	3.x	DOM操作、AJAX请求
Layui	2.8.x	UI框架
Konva	5.3.x	2D画布渲染
ECharts	5.3.2	图表渲染
MQTT.js	4.x	MQTT通信

---

二、项目结构

2.1 目录结构

ricon/
├── assets/                    # 静态资源
│   ├── css/                   # 样式文件
│   │   ├── common/            # 公共样式
│   │   ├── font/              # 字体文件
│   │   ├── editor.css         # 编辑器样式
│   │   ├── view.css           # 监控页面样式
│   │   └── reset.css          # 样式重置
│   ├── images/                # 图标和图片
│   │   ├── buttons/           # 工具栏按钮图标
│   │   └── icons/             # 通用图标
│   ├── js/                    # JavaScript代码
│   │   ├── core/              # 核心模块
│   │   │   ├── base/          # 基础类
│   │   │   ├── stage/         # 场景相关模块
│   │   │   ├── utils/         # 工具类
│   │   │   ├── config/        # 配置管理
│   │   │   ├── license/       # 授权管理
│   │   │   ├── InitManager.js # 初始化管理器
│   │   │   ├── ModuleManager.js # 模块管理器
│   │   │   ├── DataClient.js  # 统一数据客户端
│   │   │   ├── stageOperation.js # 场景操作核心
│   │   │   ├── moduleAnimation.js # 模块动画处理
│   │   │   ├── webSocketClient.js # WebSocket客户端
│   │   │   ├── mqttClient.js  # MQTT客户端
│   │   │   ├── httpClient.js  # HTTP客户端
│   │   │   └── TimerManager.js # 定时器管理
│   │   ├── modules/           # 业务模块
│   │   │   ├── editor.js      # 编辑器业务逻辑
│   │   │   ├── view.js        # 监控页面业务逻辑
│   │   │   ├── preview.js     # 预览页面业务逻辑
│   │   │   └── echartOption.js # ECharts配置
│   │   ├── libs/              # 第三方库
│   │   │   ├── jquery/        # jQuery
│   │   │   ├── layui-master/  # Layui
│   │   │   ├── konva-master/  # Konva
│   │   │   ├── echart5.3.2/   # ECharts
│   │   │   ├── mqtt/          # MQTT.js
│   │   │   └── zTree_v3/      # zTree
│   │   └── common/            # 工具函数
│   │       ├── tool.js        # 工具函数库
│   │       ├── browserUtils.js # 浏览器工具
│   │       └── provincesData.js # 省份数据
│   ├── json/                  # 组件配置文件
│   │   ├── basic-components.json  # 基础组件配置
│   │   ├── more-components.json   # 更多组件配置
│   │   └── screen-templates.json  # 模板配置
│   └── metagraphs/            # 组件图标资源
│       ├── basic/             # 基础组件图标
│       ├── graphic/           # 装饰图形图标
│       └── echart/            # 图表组件图标
├── config/                    # 配置文件
│   └── apiClient.js           # API客户端配置
├── docs/                      # 文档
├── editor.html                # 组态编辑器入口
├── view.html                  # 组态查看器入口
├── preview.html               # 组态预览入口
└── favicon.svg                # 网站图标

2.2 核心目录说明

目录	说明
assets/js/core/	核心模块，包含初始化、通信、组件管理等
assets/js/modules/	业务模块，包含编辑器、查看器、图表配置
assets/js/libs/	第三方库，如jQuery、Layui、Konva、ECharts
assets/json/	组件配置文件，定义所有可拖拽组件
assets/metagraphs/	组件图标资源，SVG/PNG格式
config/	系统配置，包含API地址、认证等

---

三、核心模块说明

3.1 初始化管理器 (InitManager)

文件路径：assets/js/core/InitManager.js

负责管理模块的注册和初始化流程，处理模块依赖关系，确保模块按正确顺序初始化。

核心方法：

// 注册模块
window.InitManager.registerModule('MyModule', () => {
  console.log('MyModule initialized');
}, ['DependencyModule']);

// 开始初始化
window.InitManager.init(() => {
  console.log('所有模块初始化完成');
});

// 获取模块状态
window.InitManager.getModuleStatus('MyModule');

3.2 模块管理器 (ModuleManager)

文件路径：assets/js/core/ModuleManager.js

负责模块的注册、动态加载、卸载和依赖管理，支持按需加载模块以提高性能。

核心方法：

// 注册模块
window.ModuleManager.registerModule('MyModule', {
  path: 'path/to/module.js',
  dependencies: ['DependencyModule'],
  initFn: () => {
    return { name: 'MyModule' };
  }
});

// 加载模块
window.ModuleManager.loadModule('MyModule').then(module => {
  console.log('模块加载成功:', module);
});

3.3 统一数据客户端 (DataClient)

文件路径：assets/js/core/DataClient.js

统一管理HTTP、MQTT、WebSocket通信，提供一致的数据订阅和发布接口，支持自动重连和错误处理。

客户端类型：

类型	枚举值	说明
HTTP	http	HTTP轮询通信
MQTT	mqtt	MQTT消息通信
WebSocket	websocket	WebSocket实时通信

连接状态：

状态	枚举值	说明
DISCONNECTED	disconnected	未连接
CONNECTING	connecting	连接中
CONNECTED	connected	已连接
RECONNECTING	reconnecting	重连中
ERROR	error	连接错误

核心方法：

// 创建WebSocket客户端
var wsClient = window.DataClient.createWebSocketClient('ws_default', {
  url: 'ws://localhost:8080/ws',
  heartbeat: 30000,
  reconnect: true
});
wsClient.connect();
wsClient.subscribe('data', function(data) {
  console.log('收到数据:', data);
});

// 创建MQTT客户端
var mqttClient = window.DataClient.createMqttClient('mqtt_default', {
  url: 'ws://localhost:9001',
  clientId: 'client_001',
  username: 'user',
  password: 'pass',
  topic: 'device/data'
});
mqttClient.connect();
mqttClient.subscribe('device/data', function(data) {
  console.log('收到MQTT数据:', data);
});

// 创建HTTP客户端
var httpClient = window.DataClient.createHttpClient('http_default', {
  timeout: 30000
});
httpClient.startPolling({
  url: '/api/data',
  interval: 5,
  onMessage: function(data) {
    console.log('轮询数据:', data);
  }
});

3.4 API客户端 (ApiClient)

文件路径：config/apiClient.js

提供与后端服务的通信接口，包含场景保存/查询、模板管理、图片管理、硬件数据获取等功能。

系统配置：

var SystemConfig = {
  serviceIpPort: "http://www.ricon.cloud:81/prod-api",
  apiPrefix: "/api",
  timeout: 30000,
  retryCount: 3,
  retryDelay: 1000
};

核心方法：

方法	说明	参数
saveStage()	保存场景	stageDatajson, dataKeyArray, stageBase64, UrlParam
selectStageById()	查询场景	UrlParam(stageId, token)
saveTemplateStage()	保存模板	stageDatajson, stageModule_id, stageBase64, stageModuleName, UrlParam
templateStageList()	获取模板列表	UrlParam
pictureList()	获取图片列表	UrlParam, classId
getHardwareData()	获取硬件数据树	UrlParam

---

四、组件系统

4.1 组件配置文件

组件配置文件定义了所有可拖拽的组件，包含组件名称、图标、JSON配置等信息。

配置文件路径：

• assets/json/basic-components.json - 基础组件
• assets/json/more-components.json - 更多组件

4.2 组件配置结构

{
  "groupName": "交互组件",
  "moduleItem": [
    {
      "moduleName": "变量1",
      "iconBase64": "assets/metagraphs/basic/interactive/bianliang1.png",
      "moduleJson": {
        "attrs": {
          "draggable": true,
          "name": "jyzt_module_group",
          "moduleType": "TextLableValue",
          "dataKey": [{"key": "", "name": ""}],
          "methodCall": "setTextValueNew",
          "moduleAttr": [...]
        },
        "className": "Group",
        "children": [...]
      }
    }
  ]
}

4.3 组件类型说明

组件类型	说明	示例
TextLableValue	文本标签值	变量显示
VALUE	数值显示	数值变量
INPUT_BOX	输入框	原生DOM输入框，支持接收/发送数据点绑定
STATUSLIGHT	状态灯	设备状态指示
ELECTRIC	电气符号	开关、调压符号
SPRINKLING	喷灌组件	喷灌机
HTML_IFRAME	网页嵌入	网页组件
ECHART_GAUGE	仪表盘	仪表盘图表
ECHART_GAUGE_NEW	仪表盘新	新式仪表盘
ECHART_GAUGE4_NEW	仪表盘4新	四色仪表盘
ECHART_THERMOMETER	温度计	温度计图表
ECHART_realTimeLine	实时折线图	实时数据折线图
ECHART_realTimeLineNew	实时折线图新	多数据系列折线图
ECHART_realTimeBarGraph	实时柱状图	实时数据柱状图
ECHART_realTimePieGraph	实时饼图	实时数据饼图
ECHART_realTimeCircularGraph	实时环形图	实时数据环形图
ECHART_SCATTER	散点图	散点图表
ECHART_KLINE	K线图	K线图表
ECHART_RADAR	雷达图	雷达图表
ECHART_HEATMAP	热力图	热力图表
ECHART_BOXPLOT	箱线图	箱线图表

---

五、图表系统

5.1 ECharts配置

文件路径：assets/js/modules/echartOption.js

定义各种ECharts图表的默认配置选项，支持以下图表类型：

方法名	图表类型	组件类型
gaugeNew()	仪表盘新	ECHART_GAUGE_NEW
gauge()	仪表盘	ECHART_GAUGE
gauge2()	仪表盘2	-
gauge3()	仪表盘3	-
gauge4()	仪表盘4	-
gauge4New()	仪表盘4新	ECHART_GAUGE4_NEW
gauge5()	仪表盘5	-
windu()	温度计	ECHART_THERMOMETER
realTimeLine()	实时折线图	ECHART_realTimeLine
realTimeLine2()	实时折线图2	-
realTimeBarGraph()	实时柱状图	ECHART_realTimeBarGraph
realTimePieGraph()	实时饼图	ECHART_realTimePieGraph
realTimeCircularGraph()	实时环形图	ECHART_realTimeCircularGraph
scatter()	散点图	ECHART_SCATTER
candlestick()	K线图	ECHART_KLINE
radar()	雷达图	ECHART_RADAR
boxplot()	箱线图	ECHART_BOXPLOT
heatmap()	热力图	ECHART_HEATMAP
graph()	关系图	-
lines()	路径图	-
tree()	树图	-
treemap()	矩形树图	-
sunburst()	旭日图	-
parallel()	平行坐标系	-
sankey()	桑基图	-
funnel()	漏斗图	-
pictorialBar()	象形柱图	-
calendar()	日历坐标系	-
matrix()	矩阵坐标系	-

5.2 图表配置格式

在组件配置中引用图表配置：

{
  "moduleName": "散点图",
  "iconBase64": "assets/metagraphs/basic/echart/scatter.svg",
  "moduleJson": {
    "attrs": {
      "draggable": true,
      "name": "jyzt_module_group",
      "moduleType": "ECHART_SCATTER",
      "echartURL": "EchartOption.prototype.scatter",
      "dataKey": [{"key": "", "name": ""}],
      "methodCall": "setEchart_GaugeValue",
      "moduleAttr": [...]
    },
    "className": "Group",
    "children": [...]
  }
}

关键配置项说明：

配置项	说明	示例
moduleType	组件类型	ECHART_SCATTER
echartURL	ECharts配置方法路径	EchartOption.prototype.scatter
dataKey	数据键数组	[{"key": "value1", "name": "数值1"}]
methodCall	数据更新方法	setEchart_GaugeValue

---

六、通信配置

6.1 通信方式

系统支持三种通信方式，可在编辑器右侧面板"通信"标签页配置：

通信方式	用途	配置项
WebSocket	实时双向通信	URL地址、心跳间隔、自动重连
MQTT	IoT设备通信	MQTT地址、客户端ID、用户名、密码、订阅主题、QoS等级
HTTP	REST API调用	支持多个HTTP配置项

6.2 通信配置示例

{
  "communicationConfig": {
    "websocket": {
      "enabled": true,
      "url": "ws://localhost:8080/ws",
      "heartbeat": 10,
      "reconnect": "1"
    },
    "mqtt": {
      "enabled": true,
      "url": "ws://localhost:9001",
      "clientId": "client_001",
      "username": "user",
      "password": "pass",
      "topic": "device/data",
      "qos": 1
    },
    "hardwareData": {
      "enabled": true,
      "url": "/api/device/hardware-data",
      "headers": "{\"Content-Type\": \"application/json\"}"
    }
  }
}

6.3 硬件数据获取

硬件数据用于组件的数据点配置，返回树形结构：

[
  {
    "children": [
      {
        "children": [
          {"id": "d1a001", "name": "车辆"},
          {"id": "d1a002", "name": "访客"}
        ],
        "id": "device001a",
        "name": "园区大门"
      }
    ],
    "id": "device001",
    "name": "新智慧园区"
  }
]

---

七、集成方式

7.1 独立部署

将ricon目录部署到Web服务器即可独立运行：

# 开发模式
cd ruoyi-ui
npm run dev

# 生产构建
npm run build
# 将dist/ricon目录部署到Web服务器

7.2 嵌入第三方系统

通过iframe嵌入到第三方系统：

<!-- 嵌入编辑器 -->
<iframe src="/ricon/editor.html" width="100%" height="800px" frameborder="0"></iframe>

<!-- 嵌入查看器 -->
<iframe src="/ricon/view.html?stageId=1" width="100%" height="800px" frameborder="0"></iframe>

<!-- 嵌入预览 -->
<iframe src="/ricon/preview.html?stageId=1" width="100%" height="800px" frameborder="0"></iframe>

7.3 URL参数

参数	说明	示例
stageId	场景ID	?stageId=1
token	认证Token	?token=abc123

7.4 后端接口集成

系统需要后端提供以下API接口：

接口路径	方法	说明
/api/saveStage	POST	保存场景
/api/selectStageById	GET	查询场景
/api/saveTemplateStage	POST	保存模板
/api/templateStageList	GET	获取模板列表
/api/templateClassList	GET	获取模板分类
/api/deleteTemplateStageById	POST	删除模板
/api/pictureClassList	GET	获取图片分类
/api/pictureList	GET	获取图片列表
/api/deletePictureById	POST	删除图片
/api/device/hardware-data	POST	获取硬件数据树

7.5 API接口详细说明

7.5.1 保存场景

接口：POST /api/saveStage

请求参数：

参数名	类型	说明	必填
stageDatajson	String	场景JSON数据	是
dataKeyArray	Array	数据键数组	否
stageBase64	String	场景缩略图Base64	否
stageId	String	场景ID（更新时）	否

响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "stageId": "1"
  }
}

7.5.2 查询场景

接口：GET /api/selectStageById

请求参数：

参数名	类型	说明	必填
stageId	String	场景ID	是

响应：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "stageDatajson": "{...}",
    "dataKeyArray": [...],
    "stageBase64": "data:image/png;base64,..."
  }
}

7.5.3 获取硬件数据

接口：POST /api/device/hardware-data

请求参数：无

响应：

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": "device001",
      "name": "新智慧园区",
      "children": [
        {
          "id": "device001a",
          "name": "园区大门",
          "children": [
            {"id": "d1a001", "name": "车辆"},
            {"id": "d1a002", "name": "访客"}
          ]
        }
      ]
    }
  ]
}

---

八、自定义开发

8.1 添加新组件

1. 在assets/json/basic-components.json中添加组件配置
2. 在assets/metagraphs/中添加组件图标
3. 在assets/js/core/moduleAnimation.js中添加数据更新方法（如有需要）

8.2 添加新图表

1. 在assets/js/modules/echartOption.js中添加图表配置方法
2. 在assets/json/basic-components.json中注册图表组件
3. 添加图表图标到assets/metagraphs/basic/echart/

示例：添加自定义图表

// 在echartOption.js中添加
EchartOption.prototype.myCustomChart = function() {
  var option = {
    tooltip: {
      trigger: 'axis'
    },
    xAxis: {
      type: 'category',
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']
    },
    yAxis: {
      type: 'value'
    },
    series: [{
      type: 'line',
      data: [120, 200, 150, 80, 70]
    }]
  };
  return option;
};

8.3 扩展通信协议

通过DataClient模块扩展新的通信协议：

var CustomClientWrapper = function(id, type, config) {
  this.id = id;
  this.type = type;
  this.config = Object.assign({}, DataClient.defaultConfig, config);
  this.state = ConnectionState.DISCONNECTED;
};

CustomClientWrapper.prototype = {
  connect: function() { /* ... */ },
  disconnect: function() { /* ... */ },
  subscribe: function(topic, callback) { /* ... */ },
  publish: function(topic, message) { /* ... */ }
};

DataClient.createCustomClient = function(id, config) {
  var client = new CustomClientWrapper(id, 'custom', config);
  this._clients[id] = client;
  return client;
};

---

九、性能优化

9.1 开发模式配置

在editor.html中配置开发模式，禁用缓存便于调试：

if (window.JsonLoader) {
  JsonLoader.setConfig({
    isDevMode: true,
    enableCache: false,
    enableServerValidation: false
  });
}

9.2 资源加载优化

系统采用以下优化策略：

• CSS异步加载（使用preload + onload）
• 关键资源同步加载，非关键资源异步加载
• 模板缓存机制
• 图片懒加载

9.3 缓存配置

配置项	说明	默认值
isDevMode	开发模式，禁用缓存	true
enableCache	启用缓存	false
enableServerValidation	启用服务端验证	false

---

十、故障排查

10.1 常见错误

错误信息	原因	解决方案
ECHART_SCATTER: 无法获取图表配置 EchartOption.prototype.scatter	echartURL配置错误	确认echartURL格式为EchartOption.prototype.xxx
WebSocket连接失败	服务端未启动或地址错误	检查WebSocket服务是否正常运行
获取硬件数据失败	接口未配置或不可用	在通信面板配置硬件数据接口
保存场景失败	后端接口错误或权限不足	检查后端服务和认证Token
组件拖拽无反应	Konva库加载失败	检查Konva库是否正确加载
图表不显示	ECharts库加载失败	检查ECharts库是否正确加载

10.2 调试技巧

1. 打开浏览器开发者工具（F12）
2. 查看Console面板的日志信息
3. 查看Network面板的请求状态
4. 使用window.Logger输出调试信息
5. 检查SystemConfig配置是否正确
6. 验证API接口是否可访问

---

十一、版本信息

项目	版本
Ricon组态系统	1.0.0
jQuery	3.x
Layui	2.8.0-rc6
Konva	5.3.x
ECharts	5.3.2
MQTT.js	4.x

---

附录：文件路径速查表

文件	路径
编辑器入口	editor.html
查看器入口	view.html
预览入口	preview.html
API配置	config/apiClient.js
初始化管理器	assets/js/core/InitManager.js
模块管理器	assets/js/core/ModuleManager.js
数据客户端	assets/js/core/DataClient.js
ECharts配置	assets/js/modules/echartOption.js
基础组件配置	assets/json/basic-components.json
组件图标	assets/metagraphs/
场景操作核心	assets/js/core/stageOperation.js
模块动画处理	assets/js/core/moduleAnimation.js
WebSocket客户端	assets/js/core/webSocketClient.js
MQTT客户端	assets/js/core/mqttClient.js
HTTP客户端	assets/js/core/httpClient.js

---

附录2：接口响应码说明

响应码	说明
200	成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
500	服务器内部错误

---

文档版本：v1.1.0
创建日期：2026年
更新日期：2026年9月
作者：Ricon组态开发团队

技术文档

👉 演示地址：http://www.ricon.cloud:81
👉 官网地址：http://www.ricon.cloud