Ricon组态系统集成说明书

by————组态2026-06-19 10:11

一、概述

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

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

核心方法：

javascript 复制代码 
// 注册模块
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

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

核心方法：

javascript 复制代码 
// 注册模块
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 连接错误

核心方法：

javascript 复制代码 
// 创建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

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

系统配置：

javascript 复制代码 
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 组件配置结构

json 复制代码 
{
  "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 数值显示 数值变量
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 图表配置格式

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

json 复制代码 
{
  "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 通信配置示例

json 复制代码 
{
  "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 硬件数据获取

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

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

七、集成方式

7.1 独立部署

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

bash 复制代码 
# 开发模式
cd ruoyi-ui
npm run dev

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

7.2 嵌入第三方系统

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

html 复制代码 
<!-- 嵌入编辑器 -->
<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（更新时） 否

响应：

json 复制代码 
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "stageId": "1"
  }
}
7.5.2 查询场景

接口 ：GET /api/selectStageById

请求参数：

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

响应：

json 复制代码 
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "stageDatajson": "{...}",
    "dataKeyArray": [...],
    "stageBase64": "data:image/png;base64,..."
  }
}
7.5.3 获取硬件数据

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

请求参数：无

响应：

json 复制代码 
{
  "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/

示例：添加自定义图表

javascript 复制代码 
// 在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模块扩展新的通信协议：

javascript 复制代码 
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中配置开发模式，禁用缓存便于调试：

javascript 复制代码 
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.0.0

创建日期 ：2026年

更新日期 ：2026年

作者 ：Ricon组态开发团队

立即体验

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

🌐 官网地址: http://www.ricon.cloud

热门推荐
012026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点062026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？07AI科技热点日报 | 2026年6月1日08Codex 下载安装指南：Windows 和 macOS 官方版下载09上线仅72小时被强制下架：Claude Fable 5 的短命10AI一周事件 · 2026-06-03 至 2026-06-09