VisualHMI 系统回调函数：on_init/on_run/on_press/on_update 全解

系统回调是 LUA 和 HMI 内核之间的事件接口：内核在特定时机自动调你的函数，你不用轮询、不用自己触发。搞懂每个回调的触发时机和限制，是写出稳定脚本的前提。

1. 回调总表

2. on_run：周期调度（注意别卡死）

on_run 是周期回调，里面干活的时长必须远小于周期。三个禁忌：

• Modbus RTU Master 高频写入易总线堵塞——on_run 里别每秒狂发写帧
• 不可用 delay_ms、长循环、网络同步——阻塞主循环，画面全卡
• 严禁 set_run_cycle 死锁——回调里改周期可能造成永不触发

function on_init()
  set_run_cycle(1000)     -- 设定 1 秒周期
end
function on_run(screen)
  -- 每秒做一次的事情：状态轮询、超时判断
end

3. on_press：触摸回调与空闲待机

on_press(state, x, y)，state：0=抬起、1=按下、2=长按。每 100ms 最多触发一次。典型用途是空闲待机节能：一段时间没触摸自动熄屏/跳主页。

_IDLE_TIMEOUT = 300000   -- 5分钟无操作
_idle_tick = 0
function on_press(state, x, y)
  _idle_tick = 0          -- 有触摸就重置计时
end
function on_run(screen)
  _idle_tick = _idle_tick + 1000   -- 假设周期1s
  if _idle_tick >= _IDLE_TIMEOUT then
    set_screen(0)         -- 跳回主画面
    _idle_tick = 0
  end
end

4. on_update：数据驱动（优先用这个）

on_update(slave, vtype, addr) 在变量值变化时触发，是数据驱动模式——比 on_run 轮询省资源。三个特性必须知道：

• 外部串口/Modbus 主站写入不触发——只对 HMI 内部变量变化生效
• on_update 内调 set_xxx 被屏蔽——防无限递归，改值不会再次触发
• 全局变量 _EN_ON_UPDATA_API_ 控制开关——置 0 可临时禁用，批量初始化时用

_EN_ON_UPDATA_API_ = 0    -- 初始化期间关回调
-- ... 批量写寄存器 ...
_EN_ON_UPDATA_API_ = 1    -- 开回回调

function on_update(slave, vtype, addr)
  if vtype == VT_LW then
    if addr == 0x1000 then
      -- LW1000 变化了，处理业务
    end
  end
end

5. on_screen_change：画面切换后初始化

画面切换完成后触发，做该画面的初始化、状态同步、资源加载——比在切屏前处理更稳。

整理自 广州大彩科技 VisualHMI 开发文档（hmi-doc.gz-dc.com）LUA 教程「系统回调」，版权归大彩科技所有。