Ricon组态系统集成指南

Ricon组态系统完整技术文档基于Web的可视化组态编辑和实时监控平台版本v1.0.1 | 更新时间2024年12月文档目录系统概述技术架构核心功能组件系统开发指南最佳实践故障排查1. 系统概述1.1 产品简介Ricon组态系统是一个基于Web技术的可视化组态编辑和实时监控平台。系统采用纯前端架构无需安装客户端支持在浏览器中直接进行组态画面编辑、实时数据监控和场景管理。1.2 核心优势零部署成本- 纯Web架构浏览器直接访问实时数据监控- 支持WebSocket、MQTT、HTTP多种通信方式丰富的组件库- 内置200工业组件和图元高性能渲染- 基于Konva.js的Canvas 2D渲染引擎易于集成- 标准的RESTful API和WebSocket协议响应式设计- 支持PC、平板、移动端多种设备1.3 适用场景工业监控- 生产线监控、设备状态展示楼宇自控- 智能楼宇、能耗监控水务管理- 污水处理、供水监控⚡电力系统- 电力监控、配电管理交通管控- 智慧交通、信号控制物联网应用- IoT设备监控、数据可视化1.4 技术栈前端框架与库技术版本用途特点Konva.js5.x2D画布渲染引擎高性能图形绘制支持复杂交互Layui2.8UI组件框架企业级UI丰富的组件库jQuery3.xDOM操作简化DOM操作和事件处理ECharts5.3.2数据可视化专业的图表库支持实时数据通信协议协议通信模式适用场景性能特点WebSocket实时双向高频数据更新低延迟、高实时性MQTT发布/订阅IoT设备监控轻量级、适合大量设备HTTP/HTTPS请求/响应低频数据更新兼容性好、实现简单核心技术特性Canvas 2D渲染- 基于Konva.js的高性能图形渲染引擎JSON配置驱动- 场景和组件采用JSON格式存储便于序列化和传输SafeJSON解析- 内置window.SafeJSON提供安全的JSON解析parse()- 标准JSON解析parseStrict()- 严格模式解析parseFlexible()- 兼容历史非严格JSON格式统一配置中心- 集中管理所有配置项支持动态加载和热更新初始化管理器- 智能管理模块依赖关系优化初始化顺序动态模块加载- 按需加载模块减少初始加载时间异步资源加载- 优化资源加载顺序提高首屏加载速度内存泄漏防护- 自动跟踪和清理资源提高系统稳定性安全增强- 内置XSS和CSRF防护机制模块化架构- 核心功能拆分为14个独立模块采用协调器模式管理代码质量保障- 严格模式、规范命名、统一代码风格、完整注释2. 技术架构2.1 系统架构图┌─────────────────────────────────────────────────┐ │ Web浏览器客户端 │ ├─────────────────────────────────────────────────┤ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 编辑器 │ │ 预览页面 │ │ 监控页面 │ │ │ │editor.html│ │preview.html││view.html │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ 核心引擎层Konva 业务逻辑 │ │ │ │ - stageOperation.js │ │ │ │ - stageView.js │ │ │ │ - moduleAnimation.js │ │ │ └─────────────────────────────────────┘ │ │ │ │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ 系统优化层 │ │ │ │ - ConfigCenter.js (配置中心) │ │ │ │ - InitManager.js (初始化管理) │ │ │ │ - ModuleManager.js (模块管理) │ │ │ │ - ResourceLoader.js (资源加载) │ │ │ │ - MemoryLeakProtector.js (内存防护) │ │ │ │ - SecurityManager.js (安全管理) │ │ │ └─────────────────────────────────────┘ │ │ │ │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ 通信层 │ │ │ │ - webSocketClient.js │ │ │ │ - mqttClient.js │ │ │ │ - httpClient.js │ │ │ └─────────────────────────────────────┘ │ └─────────────────┬──────────────────────────────┘ │ ┌─────────┴─────────┐ │ │ ┌───────▼──────┐ ┌───────▼──────┐ │ 后端API服务 │ │ WebSocket │ │ (RESTful) │ │ MQTT服务器 │ └──────────────┘ └──────────────┘2.2 模块化架构设计核心模块划分stageOperation.js已重构为模块化架构包含14个独立功能模块模块分类模块文件功能说明主要方法核心功能stageInit.js场景初始化initStage,initResolutionstageProperties.js场景属性配置initStageProperties,setStageSizestageConfig.js场景配置管理setStageCache,getStageJson通信数据stageCommunication.js通信配置管理initCommunicationConfigstageUtils.js工具函数getStageAllDataKey,getStageBase64用户交互stageViewControl.js视图控制stageMaxMin,addMouseListensstageKeyboard.js键盘事件setStageKeyboardEventstageGuides.js辅助线getAnchorArray,drawGuides组件操作stageModule.js组件管理addModuleToStage,deleteModulestageAlign.js组件对齐alignModulemoduleAttributes.js组件属性showModuleAttr,setModuleAttr系统功能stageUndoRedo.js撤销恢复ctrlZ,ctrlYstageImportExport.js导入导出import,exportstagePanels.js组件库面板setBasicPanel,setGraphicPanel架构优势代码组织结构优化单一职责原则 - 每个模块只负责一个特定功能领域高内聚低耦合 - 模块内部功能紧密相关模块间依赖最小化清晰的依赖关系 - 明确定义的模块加载顺序和依赖关系可维护性提升易于定位问题 - 功能模块化bug定位更快速准确独立升级维护 - 单个模块的更新不会影响其他功能代码复用性强 - 通用模块可在其他项目中直接使用可扩展性增强插件化架构 - 新功能可以通过独立模块形式添加配置驱动 - 通过配置文件即可启用/禁用特定功能接口标准化 - 统一的模块接口规范便于团队协作2.3 核心模块说明2.3.1 编辑器模块 (editor.html)功能职责组态画面编辑和设计组件库管理和组件选择属性配置和场景管理导入导出和模板管理关键文件assets/js/modules/editor.js- 编辑器业务逻辑assets/js/core/stageOperation.js- 场景操作核心2.3.2 监控模块 (view.html)功能职责场景渲染和数据展示实时数据接收和更新动画效果处理用户交互响应关键文件assets/js/modules/view.js- 监控页面逻辑assets/js/core/stageView.js- 场景视图渲染assets/js/core/moduleAnimation.js- 动画处理2.3.3 通信模块WebSocket客户端(webSocketClient.js)自动重连机制心跳保活连接状态管理消息队列处理MQTT客户端(mqttClient.js)WebSocket协议连接主题订阅/取消订阅QoS质量等级支持认证和加密HTTP客户端(httpClient.js)轮询请求支持自定义请求头和参数GET/POST/PUT/DELETE方法错误重试机制4. 核心功能4.1 编辑器功能4.1.1 画布操作画布缩放鼠标滚轮缩放需按住Ctrl键工具栏缩放滑块0-500%快捷键支持画布平移空格键鼠标拖拽画布边缘拖拽当内容超出可视区域辅助功能网格显示/隐藏对齐辅助线标尺显示可选4.1.2 组件操作基础操作拖拽添加组件点击选中组件拖拽移动位置拖拽调整大小右键菜单操作多选操作Ctrl点击多选CtrlA全选框选鼠标拖拽选择区域对齐操作左对齐、右对齐、居中对齐上对齐、下对齐、垂直居中水平分布、垂直分布图层操作上移一层、下移一层置顶、置底图层树管理4.1.3 属性配置通用属性位置和大小X、Y、Width、Height旋转角度透明度边框和填充字体样式字体、大小、颜色、粗细数据绑定硬件设备数据点选择数据缩放配置条件判断配置状态颜色映射事件配置点击事件写值、跳转、脉冲悬停效果自定义事件4.1.4 撤销恢复系统实现了基于栈的撤销/恢复机制// 使用ArrayStack实现varstackZnewArrayStack();// 撤销栈varstackYnewArrayStack();// 恢复栈// 支持的操作-组件添加/删除-属性修改-位置/大小调整-图层操作快捷键CtrlZ- 撤销CtrlY- 恢复4.2 监控功能4.2.1 实时数据更新更新机制基于WebSocket的实时推送基于MQTT的发布订阅基于HTTP的轮询请求支持多种通信方式同时使用更新流程数据接收 → 数据解析 → 场景数据更新 → 组件数据绑定 → 画面重绘4.2.2 预览测试数据输入preview.html预览页面支持在顶部输入框中手动输入测试数据并应用到场景。推荐格式标准 JSON{a03:0,a04:98,d3a002:8}兼容格式历史写法{a03:0,a04:98,d3a002:8}key 不加引号说明兼容解析由window.SafeJSON.parseFlexible()支持避免使用eval。4.2.3 动画效果支持的动画类型旋转动画- 风机、电机等旋转设备流动动画- 水流、电流等流动效果闪烁动画- 报警灯、指示灯闪烁渐变动画- 颜色渐变、透明度变化动画配置动画速度控制动画方向设置动画循环模式动画触发条件4.2.4 状态指示颜色状态根据数据值显示不同颜色支持多段颜色映射支持渐变色图片状态根据数据值切换图片支持多状态图片支持状态图标数值显示实时数值显示单位显示数据格式化4.3 场景管理4.3.1 场景保存保存内容场景JSON数据所有组件和配置场景缩略图Base64编码绑定数据点列表场景元数据名称、描述、分辨率等保存格式{stageId:stage_001,stageName:场景名称,width:1920,height:1080,components:[...],config:{...}}4.3.2 场景加载加载方式通过场景ID加载从模板库加载导入JSON文件加载流程场景ID → API请求 → 获取场景数据 → 解析JSON → 渲染场景4.3.3 场景模板模板功能保存常用场景为模板从模板快速创建场景模板分类管理模板分享6. 组件系统6.1 组件分类6.1.1 基础组件文本组件静态文本显示支持数据绑定显示丰富的字体样式配置按钮组件点击事件配置写值功能画面跳转脉冲信号发送图片组件静态图片动态图片切换状态图片映射图表组件ECharts图表集成柱状图、折线图、饼图等实时数据更新丰富的图表配置6.1.2 图元组件电气图元丰富的工业电气符号支持自定义图元状态颜色映射开关组件开关图标开关状态控制点击切换指示灯组件状态指示灯多状态颜色闪烁效果6.1.3 高级组件表格组件数据表格展示实时数据更新排序和筛选iframe组件嵌入外部网页嵌入ECharts图表嵌入数据表格动画组件旋转动画流动动画闪烁动画6.2 组件属性配置6.2.1 通用属性属性类型说明xNumberX坐标位置yNumberY坐标位置widthNumber宽度heightNumber高度rotationNumber旋转角度度opacityNumber透明度0-1visibleBoolean是否可见6.2.2 数据绑定属性硬件数据点绑定从硬件设备树选择变量支持虚拟变量绑定支持多数据点绑定数据缩放配置线性缩放自定义映射规则单位转换条件判断配置多条件判断逻辑运算符AND、OR条件组合6.2.3 样式属性字体样式字体族字体大小字体颜色字体粗细字体样式正常、斜体边框样式边框宽度边框颜色边框样式实线、虚线等填充样式填充颜色渐变填充图片填充6.3 组件开发6.3.1 开发流程创建编辑模块在modules/edit/目录创建HTML和JS文件实现属性编辑界面注册组件在assets/json/basic.json添加组件定义配置组件图标和属性实现渲染逻辑在stageOperation.js添加创建逻辑在stageView.js添加渲染逻辑实现数据更新在stageView.js实现数据更新方法处理WebSocket数据推送6.3.2 组件模板编辑模块模板// editMyComponent.jsfunctioninitMyComponentEditor(moduleObject){// 初始化编辑器// 绑定事件// 加载默认值}functionsaveMyComponentConfig(moduleObject){// 保存配置// 更新组件属性}组件注册模板{type:MyComponent,name:我的组件,icon:assets/images/icons/my-component.png,attributes:{width:100,height:100,color:#333333}}5. 开发指南5.1 代码结构5.1.1 核心文件说明文件说明主要功能stageOperation.js场景操作核心组件创建、属性配置、场景管理stageView.js场景视图渲染场景渲染、数据更新、动画处理webSocketClient.jsWebSocket客户端连接管理、消息处理mqttClient.jsMQTT客户端连接管理、主题订阅httpClient.jsHTTP客户端请求管理、轮询处理moduleAnimation.js动画处理旋转、流动、闪烁等动画5.1.2 模块化设计核心层Core提供基础功能和API不依赖业务逻辑可复用的通用模块业务层Modules编辑器业务逻辑监控页面逻辑组件编辑逻辑工具层Common通用工具函数数据格式化工具类封装5.2 开发规范5.2.1 命名规范文件命名HTML文件kebab-case如edit-button.htmlJavaScript文件camelCase如editButton.jsCSS文件kebab-case如edit-button.css变量命名变量名cameCase如stageOper常量UPPER_SNAKE_CASE如MAX_SIZE类名PascalCase如StageOperation5.2.2 代码风格JavaScript风格// 使用严格模式use strict;// 使用函数表达式而非函数声明在某些模块中varmyFunctionfunction(){// 代码};// 添加注释/** * 函数说明 * param {type} param - 参数说明 * returns {type} 返回值说明 */注释规范文件头注释说明文件用途函数注释参数和返回值关键代码注释复杂逻辑说明5.3 调试技巧5.3.1 浏览器调试开发者工具F12打开开发者工具Console查看日志和错误Network查看网络请求Sources设置断点调试常用调试代码// 查看场景对象console.log(stageOper.stage);// 查看组件列表console.log(stageOper.stage.find(Group));// 查看通信配置console.log(stageOper.stage.attrs.communicationConfig);// 查看WebSocket连接console.log(webSocketClient);5.3.2 日志记录系统在关键位置添加了console.log便于调试组件创建日志数据更新日志通信连接日志错误日志6. 最佳实践6.1 性能优化6.1.1 场景优化合理使用图层分组- 减少重绘次数避免过多组件- 单个场景建议不超过500个组件使用图片缓存- 重复使用的图片进行缓存优化动画性能- 避免复杂计算在动画循环中6.1.2 数据优化数据更新频率- 根据实际需求设置更新间隔数据点数量- 单个场景建议不超过100个数据点批量更新- 合并多个数据更新操作6.1.3 加载优化按需加载- 延迟加载非关键资源资源压缩- 压缩图片和代码CDN加速- 使用CDN加速静态资源6.2 用户体验6.2.1 操作反馈加载提示- 数据加载时显示loading操作确认- 重要操作需要确认错误提示- 友好的错误信息提示成功提示- 操作成功后的反馈6.2.2 响应速度快速响应- 用户操作立即响应异步处理- 耗时操作异步处理进度显示- 长时间操作显示进度6.3 代码质量6.3.1 可维护性模块化设计- 功能模块化低耦合代码复用- 提取公共代码文档完善- 添加必要注释和文档6.3.2 可扩展性接口抽象- 定义清晰的接口配置驱动- 使用配置文件而非硬编码插件机制- 支持组件扩展7. 故障排查7.1 安装部署问题Q: 页面空白无法显示A:检查Web服务器配置是否正确查看浏览器控制台错误信息确认所有资源文件路径正确检查浏览器兼容性Q: 图片无法加载A:检查图片路径相对路径或绝对路径确认图片文件是否存在检查Web服务器静态资源配置查看浏览器Network面板请求状态7.2 功能使用问题Q: 组件无法拖拽A:确认Konva库是否正确加载检查画布是否正常初始化查看浏览器控制台是否有错误尝试刷新页面Q: 保存失败A:检查API接口地址配置确认用户token是否有效查看网络请求响应信息检查场景JSON数据格式Q: 数据不更新A:检查WebSocket/MQTT/HTTP连接状态确认数据点绑定是否正确查看数据更新方法是否被调用检查数据格式是否符合预期Q: 控制台报错window.SafeJSON.parseFlexible is not a functionA:确认已加载assets/js/common/tool.js其中定义window.SafeJSON版本升级后请清理缓存CtrlF5避免旧资源未更新Q: 控制台报错echarts is not defined图表组件A:确认页面已引入 ECharts 脚本echarts.min.js若页面使用defer延迟加载脚本图表初始化可能早于脚本加载请检查 Network 是否成功加载脚本7.3 通信连接问题Q: WebSocket连接失败A:检查WebSocket服务器是否运行确认URL配置是否正确ws://或wss://检查防火墙和网络设置查看浏览器控制台WebSocket错误Q: MQTT连接失败A:确认MQTT.js库是否正确加载检查MQTT服务器地址WebSocket协议验证用户名密码是否正确检查客户端ID是否唯一Q: HTTP请求失败A:检查API地址是否正确确认请求头和参数格式查看CORS跨域配置检查网络连接7.4 性能问题Q: 场景加载慢A:优化场景组件数量压缩图片资源使用图片缓存检查网络带宽Q: 画面卡顿A:减少动画数量优化数据更新频率使用图层分组检查浏览器性能附录A. 快捷键列表功能快捷键保存Ctrl S预览Ctrl P撤销Ctrl Z恢复Ctrl Y复制Ctrl C粘贴Ctrl V删除Delete全选Ctrl A放大Ctrl 滚轮上缩小Ctrl 滚轮下全屏F11B. 组件属性类型类型说明示例input文本输入框文本、数字输入color颜色选择器颜色选择select下拉选择框选项选择slider滑块数值范围选择hardwareInputNew硬件设备选择数据点绑定whereStatusColorTable状态颜色表条件颜色配置valueZoomTableNew数据缩放表数据缩放配置C. 数据格式参考场景JSON结构{attrs:{width:1920,height:1080,backgroundColor:#ffffff,communicationConfig:{websocket:{enabled:true,url:ws://localhost:8080/ws,heartbeat:10,reconnect:1}},dataKeyArray:{a03:,a04:,d3a002:}},children:[{attrs:{id:component_001,moduleType:Text,x:100,y:100,width:200,height:50}}]}dataKeyArray 说明位置stage.attrs.dataKeyArray类型Objectkey 为数据点编号/devicecodevalue 为当前值初始化为用途预览/监控页用于构建messageContentTemp并进行数据合并更新D. 参考资料Konva.js 官方文档ECharts 官方文档Layui 官方文档WebSocket APIMQTT.js 文档E. 版本历史v1.0.1 (2024)系统优化和架构升级实现统一配置中心集中管理所有配置实现初始化管理器优化模块依赖管理实现动态模块加载减少初始加载时间实现异步资源加载提高首屏加载速度实现内存泄漏防护提高系统稳定性实现安全管理器增强XSS和CSRF防护优化配置管理支持动态加载和热更新优化错误处理提供更友好的用户反馈增强代码文档提高可维护性v1.0.0 (2024)初始版本发布支持可视化组态编辑支持实时数据监控支持WebSocket、MQTT、HTTP通信支持丰富的组件库文档维护本文档会持续更新请关注项目更新日志。技术支持如有问题请提交Issue或联系技术支持团队。Ricon组态系统 - 让可视化组态更简单