HMI 事件
HMI 事件用于响应点击、输入、加载和页面交互。内置控件动作无法完成所需界面行为时,再为控件配置事件。
事件脚本入口是小写 window.darra。高级事件使用设计器生成的 context,不要自行构造或绕过写权限。现场包在 C:\Darra\HMI\。
优先使用内置动作
| 动作 | 类别 | 读写 | 说明 |
|---|---|---|---|
自复位 momentary | 操作 | 写 | 按下写入按下值,松开写回松开值 |
置位 set | 操作 | 写 | 写入按下值 |
复位 reset | 操作 | 写 | 写入松开值 |
取反 toggle | 操作 | 写 | 在两值之间切换 |
打印 print | 操作 | 只读动作 | 打印当前页、指定页或报表区 |
| 页面跳转 | 导航 | 写 | 导航到指定页面 |
输入框、滑块、旋钮和开关也有内置提交行为。能用内置动作时,不要重复写事件脚本。
拖拽画面的控件事件
事件编辑器根据控件类型显示可用事件。属性名为 data-on-<event>,可选 data-on-<event>-lang(默认 js)。
| 控件族 | 类别 | 读写 | 常用事件 |
|---|---|---|---|
| 按钮、图片切换、面板、标签 | 交互 | 读事件 / 写动作 | 点击、双击、按下、释放、悬停、加载、卸载 |
| 输入和数值控件 | 输入 | 读写 | 值变化、获得焦点、失去焦点、加载、卸载 |
| 滑块和进度条 | 输入 | 读写 | 值变化、加载 |
| 指示灯 | 显示 | 只读 | 加载、值变化 |
| 仪表、趋势、图表和报警列表 | 显示 | 只读 | 加载、卸载 |
| 其他控件 | 交互 | 读事件 | 点击、加载 |
控件只显示自身支持的事件。不要假设所有控件都有相同事件。
配置步骤
- 在画布中选中控件。
- 打开事件属性。
- 选择事件名称。
- 优先选择页面动作或控件内置动作。
- 必须写 PLC 请求时,使用项目采用的 C# 风格 SCL,并保持单一、短小的请求赋值。
- 保存后在离线预览中检查界面效果,再连接运行时验证写入。
事件职责
| 可以做 | 类别 | 读写 | 说明 |
|---|---|---|---|
| 打开或关闭纯界面面板 | 界面 | 读写 | 不改变 PLC 状态 |
| 切换标签页或页面 | 导航 | 写 | darra.navigate 或内置跳转 |
| 提交一个经过授权的请求变量 | 操作 | 写 | 等完整回执 |
| 显示确认提示 | 安全 | 只读 | 危险操作 |
| 启动或停止纯显示动画 | 外观 | 只读驱动 | 不判断设备状态 |
| 清理计时器和监听器 | 生命周期 | 写清理 | 页面卸载时 |
| 不应做 | 类别 | 读写 | 说明 |
|---|---|---|---|
| 在 HMI 中实现设备状态机 | 控制 | 禁止 | 放在 PLC SCL |
| 判断安全联锁 | 控制 | 禁止 | 放在 PLC SCL |
| 直接组合多个输出形成启停序列 | 控制 | 禁止 | 只提交请求变量 |
| 用页面计时器代替 PLC 定时器 | 控制 | 禁止 | 扫描周期在 Service |
| 用本地 UI 状态冒充 PLC 真实状态 | 显示 | 禁止 | 状态来自 PLC 变量 |
设备动作应采用“页面提交请求 → PLC SCL 校验 → PLC 更新状态 → HMI 显示结果”的闭环。
代码画面与 window.darra
代码画面可以使用浏览器事件处理界面交互,但 PLC 写入仍应通过受控 API 完成。
| API | 类别 | 读写 | 说明 |
|---|---|---|---|
darra.on(event, callback) | 运行时事件 | 读 | 返回取消函数 |
darra.off(event, callback) | 运行时事件 | 写清理 | 移除指定监听器 |
darra.write(name, value) | 变量 | 写 | 单变量事务 |
darra.writeGroup(values) | 变量 | 写 | 同一事务批量 |
darra.isCommittedReceipt(receipt) | 变量 | 读 | 判断是否完整提交 |
darra.navigate(route) | 页面 | 写 | 页面跳转 |
darra.ctl(name) | 控件 | 读 | 按代码名取元素 |
常用运行时事件:
| 事件 | 类别 | 读写 | 说明 |
|---|---|---|---|
ready | 连接 | 只读 | WebSocket 已连接 |
offline | 连接 | 只读 | 已断开;应禁用写入 |
error | 诊断 | 只读 | 运行时错误 |
write_receipt | 写入 | 只读 | 写入回执 |
themeChanged | 主题 | 只读 | 主题切换 |
alarm.added | 报警 | 只读 | 新报警 |
alarm.updated | 报警 | 只读 | 报警更新 |
alarm.acknowledged | 报警 | 只读 | 已确认 |
alarm.cleared | 报警 | 只读 | 已清除 |
创建的计时器、订阅和事件监听器应在页面离开时释放。
高级事件脚本
设计器编译的高级事件脚本会收到受控 context:
| API | 类别 | 读写 | 说明 |
|---|---|---|---|
context.plc.read() | 变量 | 读 | 主动读取 |
context.plc.write() | 变量 | 写 | 受声明白名单约束 |
context.plc.subscribe() | 变量 | 读 | 订阅 |
context.events.on() / off() / once() | 事件 | 读 | 可配超时和重入 |
context.navigation.go() | 页面 | 写 | 跳转 |
context.alarms.acknowledge() / clear() / list() | 报警 | 读 + 确认 | 报警操作 |
context.i18n / context.log / context.clock | 辅助 | 读 | 翻译、日志、时钟 |
context.signal / context.abort() | 生命周期 | 写 | 取消进行中的处理 |
重入策略:serial、drop、merge。优先让设计器生成上下文。
危险操作
| 规则 | 类别 | 读写 | 说明 |
|---|---|---|---|
| 自复位或显式确认 | 安全 | 写 | 危险动作 |
| 显示将要执行的动作和目标设备 | 安全 | 只读 | 操作前可见 |
| 断线 / 只读 / 禁用 / 权限不足 | 安全 | 禁止写 | 拒绝操作 |
| PLC SCL 再检查 | 控制 | 读写 | 设备状态和联锁 |
| 无旁路 | 安全 | 禁止 | HMI 不提供绕过 PLC 安全逻辑的路径 |
验收
| 检查 | 类别 | 读写 | 期望 |
|---|---|---|---|
| 单击一次 | 交互 | 写 | 只触发一次动作 |
| 自复位按钮 | 操作 | 写 | 鼠标和触摸抬起都恢复松开值 |
| 重新进入页面 | 生命周期 | 读 | 没有重复事件 |
| 断线 | 运行 | 禁止写 | 写事件被禁用 |
| 权限不足 | 安全 | 禁止写 | 动作不可执行 |
| PLC 拒绝 | 操作 | 读回执 | 界面明确提示失败,不伪装成功 |