VisualHMI 简易数据库：easydb_* 与数据记录控件自定义模式

简易数据库（定制固件专属）是一个轻量级、无文件系统的嵌入式数据库：在 Flash 里划一块连续区域，按固定长度记录存结构化数据（参数配置、事件日志、运行记录），掉电不丢，支持运行时按需初始化。数据记录控件用「自定义」数据源模式对接，实现增删改查全流程。

1. ⚠️ Flash 地址规划（不看会变砖）

简易数据库直接操作 Flash，没有文件系统隔离机制，flashaddr 起始地址必须严格避开四类高风险区域：

• 工程资源存储区
• 资料采样块存储区
• 操作记录块存储区
• OTA 升级备份区域

总占用空间 = dataRowSize × maxCount，规划地址时把这段空间算进去，别和别的功能打架。

2. API 总表

3. 数据记录控件「自定义」模式

数据来源设为自定义时，系统不知道有多少行数据，必须由两个回调提供：

• 记录数量回调 on_get_record_count(screen_id, control_id)：返回总行数，内部调 easydb_get_count(g_db_handle)
• 记录内容回调 on_get_record_row(screen_id, control_id, row)：返回第 row 行的字符串内容

function on_get_record_count(screen_id, control_id)
  if screen_id == 0 and control_id == 1 then
    return db.getCnt(g_db_handle)
  end
end

function on_get_record_row(screen_id, control_id, row)
  local ret, msg = db.get(g_db_handle, row)
  if ret == 0 then
    return msg
  end
end

控件配置：数据来源=自定义、字符编码=UTF8、翻页控制√、控制地址 LW4000、选中行通知√（LW4004，UINT32）——选中某行时索引写进 LW4004，增删改都靠它定位。

4. 应用：db.lua 句柄封装 + 增删改查

4.1 初始化（on_init）

function on_init()
  dofile("db.lua")
  _EN_ON_UPDATA_API_ = 0
  -- 10MB 起始、不存在则创建、单条1000字节、最多1000条
  g_db_handle = db.open(10*1024*1024, 1, 1000, 1000)
  if g_db_handle == 0 then
    print("ERROR: 无法打开数据库！")
    return
  end
  db.clear(g_db_handle)               -- 清空旧数据（可选）
  db.add(g_db_handle, "Alice;Engineer;30")
  db.add(g_db_handle, "Bob;Technician;25")
  db.add(g_db_handle, "Charlie;Manager;40")
  db.add(g_db_handle, "Harden;Basketball players;36")
  _EN_ON_UPDATA_API_ = 1
end

记录格式「姓名;职业;年龄」，英文分号分隔，和表格控件解析规则一致，直接映射多列。

4.2 增删改（LW5000 按键分发）

function on_update(slave, vtype, addr)
  if addr == 0x4004 then              -- 选中行通知
    local idx = get_uint32(VT_LW, addr)
    local ret, msg = db.get(g_db_handle, idx)
    if ret == 0 then
      local parts = my_split(msg, ";")
      if parts ~= nil then
        set_uint16(VT_LW, 0x4530, idx)   -- 记录当前选中索引
        set_string(VT_LW, 0x4500, (parts[1] == nil) and "--" or parts[1])
        set_string(VT_LW, 0x4510, (parts[2] == nil) and "--" or parts[2])
        set_string(VT_LW, 0x4520, (parts[3] == nil) and "--" or parts[3])
      end
      show_dialog(1, 232, 33, 50)        -- 弹窗显示详情
    end
  elseif addr == 0x5000 then
    local key = get_uint16(VT_LW, addr)
    if key == 0 then                    -- 添加
      local name = get_string(VT_LW, 0x5010)
      local position = get_string(VT_LW, 0x5020)
      local age = get_string(VT_LW, 0x5030)
      db.add(g_db_handle, name..";"..position..";"..age..";")
    elseif key == 1 then                -- 修改（改选中行）
      local name = get_string(VT_LW, 0x4500)
      local position = get_string(VT_LW, 0x4510)
      local age = get_string(VT_LW, 0x4520)
      local idx = get_uint16(VT_LW, 0x4530)
      db.modify(g_db_handle, idx, name..";"..position..";"..age..";")
    elseif key == 2 then                -- 删除（删选中行）
      local idx = get_uint16(VT_LW, 0x4530)
      db.del(g_db_handle, idx)
    end
  end
end

db.lua 封装层每个函数都做句柄校验 + 索引越界检查（idx = count 返回 -2），这是句柄驱动设计的标准姿势：不合法就直接返回错误码，绝不往下传。

整理自 广州大彩科技 VisualHMI 开发文档（hmi-doc.gz-dc.com）LUA 教程「简易数据库」，版权归大彩科技所有。