VisualHMI Lua API 大全：回调/通信/寄存器读写函数速查表

这是 VisualHMI 平台 Lua 脚本的完整 API 手册：10 个系统回调 + 32 个读写寄存器函数 + 10 个绘图函数，共 52 个接口。写脚本前先翻这篇，比逐个翻教程快。平台基于 Lua 5.3。

0. 基础：自动生成的 main.lua

菜单 工程→脚本编程 默认生成 main.lua，自动带协议对应的数据类型定义：

ENCRYPT_ = 0        -- LUA脚本加密开关
-- 数据类型定义（随协议变化，以下为 Modbus）
VT_LW = 1           -- 内部变量
VT_RW = 2           -- FLASH掉电存储
VT_0x = 10          -- 线圈
VT_1x = 11          -- 输入点（离散输入）
VT_3x = 12          -- 输入寄存器
VT_4x = 13          -- 保持寄存器

function on_init() end
function on_run(screen) end
function on_update(slave,vtype,addr) end
function on_draw(screen_id,control_id) end

FX3U 协议下还会有 VT_M（内部继电器）、VT_D（D寄存器）等类型。on_update 里的 vtype、get/set 函数第一个参数都用这些常量。

1. 常用回调函数（10 个）

2. 读写寄存器函数（32 个）

2.0 先说两个关键机制（所有 set/get 通用）

机制一：get_xxx() 是零通信开销的。get 系列全部从 HMI 本地缓存（内存镜像）读，不产生串口帧。HMI 后台任务按工程配置的轮询周期自动从 PLC 读通信变量（如 Modbus 的 VT_3x/VT_4x）并缓存。画面控件绑定了某地址，该地址就自动进轮询列表；脚本要读没被工程引用的地址，用 start_read 显式请求同步。

机制二：set_xxx() 不一定发串口帧。只有两个条件同时满足才主动发报文：①HMI 是主机模式（Modbus Master/DCBUS/XGUS）；②串口通知没被 set_notify(0) 禁止。从机模式下 set 只更新本地镜像。

2.1 通信控制

2.2 位操作

2.3 数值读写（16/32/64 位）

所有 get 系列读本地缓存；set 系列通信触发看「机制二」。

2.4 字符串与批量

3. 绘图函数（10 个）

全部 draw_xxx 必须在 on_draw(screen_id,control_id) 回调里调用才生效，控件 ID 必须 ≠ 0。图层按控件 Z 轴（编辑器叠放顺序）管理，靠判断 control_id 分层绘制。主动刷新调 redraw()。

4. 绘图实例：switch 表驱动

源文所有绘图示例都是一个套路：on_update 读按钮键值 → redraw() → on_draw 里按键值查 switch 表选绘制函数。以画线+画圆为例：

draw_type = 0
mode = { line = 1, rect = 2, rect_alpha = 3, circle = 4, ellipse = 5, imageId = 6, text = 7 }

function on_update(slave,vtype,addr)
  if addr == 0x1000 then
    draw_type = get_uint16(VT_LW, addr)  -- 字设置按钮键值
    redraw()
  end
end

function on_draw(screen_id, control_id)
  local switch = {
    [mode.line] = function(control)
      if screen_id == 0 and control == 1 then
        set_pen_color(0xFFE0)          -- 黄色
        draw_line(225, 253, 405, 253)
        set_pen_color(0xF800)          -- 红色
        draw_line(508, 128, 508, 378, 5)
      end
    end,
    [mode.circle] = function(control)
      if screen_id == 0 and control == 1 then
        draw_circle(300, 253, 100, 0)  -- 实心圆
        draw_circle(450, 253, 150, 1)  -- 空心圆，线厚1
      end
    end,
  }
  if switch[draw_type] then switch[draw_type](control_id) end
end

整理自 广州大彩科技 VisualHMI 开发文档（hmi-doc.gz-dc.com）LUA 教程「Lua 脚本API函数接口」，版权归大彩科技所有。