FORGE KUI / learn

用 Lua 完成界面交互

连接脚本引擎,读取输入、保存名称并在 DevTools 中调试。

版本 3.61.7

第07课
准备
完成首个窗口,SDK 包含脚本支持
学完可以做
一个由 Lua 驱动的资源库属性面板
下载工程 ↓lua-lab.zip

工程与运行目标

下载 Lua 工程。它沿用 DevTools 展示中的 Forge Library,界面为英文。HTML、CSS 和 Lua 都在 index.html;main.cpp 负责窗口、窗口按钮与脚本引擎,不实现保存业务。

Lua 课程工程的真实原生运行画面

构建并找到交互区

进入解压目录,使用自己 SDK 的路径和编译配置。

  1. 执行下列命令,启动 lua_lab.exe。
  2. 在右侧 Properties 找到 Workspace name、Save changes、Reset 与保存计数。
  3. 把名称改为 My Library,点击 Save changes,看到 Saved: My Library 和计数 1。
  4. 点 Reset:名称恢复 Forge Studio,计数仍保留。
powershell
$cxxStandard = Read-Host SDK-standard
cmake -S . -B build -A x64 "-DCMAKE_CXX_STANDARD=$cxxStandard" -DKui_DIR=C:/SDK/kui-cpp/cmake
cmake --build build --config Release --parallel 4
.\build\Release\lua_lab.exe

脚本引擎的接入与退出

以下片段取自工程 main.cpp。引擎与绑定文档都必须在消息循环期间存活;退出清理见文件末尾。

cpp
    auto script = kui::ScriptEngine::create();
    if (!script) return 4;
    script->bindDocument(doc);
    script->executeScripts();
    window->setScriptEngine(script.get());

读取当前值,更新文本

Lua 的 nameInput.value 是当前编辑值。保存用局部变量维护计数,用 textContent 更新反馈;没有执行磁盘写入。Reset 只恢复输入值,不抹掉保存次数。

lua
local nameInput = document:getElementById("workspace-name")
local status = document:getElementById("status")
local counter = document:getElementById("save-count")
local savedCount = 0

local function saveWorkspace()
  local workspaceName = nameInput.value
  local nextCount = savedCount + 1
  savedCount = nextCount
  counter.textContent = tostring(savedCount)
  status.textContent = "Saved: " .. workspaceName
end

document:getElementById("save"):addEventListener("click", saveWorkspace)
document:getElementById("reset"):addEventListener("click", function()
  nameInput.value = "Forge Studio"
  status.textContent = "Workspace name restored."
end)

在断点上观察一次保存

用 --inspect 启动,打开 DevTools 的 Lua 源文件。在 saveWorkspace 中设置断点后点击保存,检查 workspaceName、savedCount 和 nextCount;继续后观察 DOM 反馈。只修改变量值不等同于源文件已修改。

powershell
.\build\Release\lua_lab.exe --inspect

练习:给空白名称加校验

在 saveWorkspace 开头验证名称,失败时显示可见错误并提前返回。使用 Lua 模式 %s 判断空白时,先确认你的业务是否需要完整 Unicode 空白规则;此处练习仅处理普通空格和换行。成功路径仍保持原计数逻辑。

  • 空白名称保存:显示错误,计数不变。
  • 有效名称连续保存两次:计数增加两次。
  • 保存 <h1>Test</h1>:显示普通文字,不创建标题节点。
  • 关闭后重开:计数从零开始,说明未实现磁盘保存。

文档有误或遗漏?

反馈此页问题 →