Lua 脚本

使用方式

Lua 是可选脚本能力，由 KUI_ENABLE_SCRIPTING 控制。运行时版本以实际交付库的 _VERSION 为准；某次构建验证的版本不能替代所有平台结论。KUI 的脚本环境不提供浏览器 JavaScript 运行时。

接入和限制

脚本用于界面事件和原生桥接时，应明确参数、错误和对象所有权。只执行应用信任的脚本；不要把外部输入直接拼成可执行文本。宿主异步工作返回 UI 线程后再访问界面。

在窗口中启用脚本

加载 HTML 后创建 ScriptEngine，绑定文档，执行脚本标签，再把引擎关联到窗口。调用方持有返回的 unique_ptr，保证引擎在窗口使用期间存活。ScriptEngine::create 返回空时，检查运行库是否包含脚本能力。

std::unique_ptr<kui::ScriptEngine> attachScripts(kui::Window& window) {
    auto engine = kui::ScriptEngine::create();
    if (!engine) return nullptr;
    engine->bindDocument(window.document());
    engine->executeScripts();
    window.setScriptEngine(engine.get());
    return engine;
}

查询元素与处理事件

下面的脚本需要页面中存在 action 按钮和 output 元素。冒号用于对象方法，textContent 是属性。添加或删除元素后，不要把旧元素引用当作永久有效的句柄。

local count = 0
local button = document:getElementById("action")
local output = document:getElementById("output")
button:addEventListener("click", function(event)
    count = count + 1
    output.textContent = "Clicks: " .. tostring(count)
end)

窗口函数与表单值

window.innerWidth()、window.innerHeight() 和 window.devicePixelRatio() 是点调用函数。document:body() 使用冒号。输入框的当前值通过 value 属性读取，默认值与 checked/defaultChecked 需要分别处理；接口名称相似不表示和浏览器脚本完全一致。

print(_VERSION)
print(window.innerWidth(), window.innerHeight())
local input = document:getElementById("name")
if input then print(input.value) end

• Lua API 目录 →
• Lua 示例 →

动画、计时器与观察器

脚本面包含 setTimeout、setInterval、requestAnimationFrame、Promise、JSON 与 DOM 观察器。持续动画应在隐藏或不再需要时停止，避免一直请求帧。document、Element 和 window 的监听器返回值与移除方式分别查对应 API。

• 计时器接口 →
• 观察器接口 →

接入顺序和退出清理

只有加载 HTML 不会替你完成脚本引擎的所有接入。使用包含脚本能力的 SDK。

1. 加载包含 text/lua 脚本的文档。
2. 创建 ScriptEngine，检查返回值；bindDocument 后 executeScripts。
3. 用 window->setScriptEngine 保持窗口与脚本帧更新关联，引擎对象保留到事件循环退出。
4. 退出时解除窗口上的引擎关联，再 unbindDocument；不要让已释放文档残留在脚本引用中。

脚本不执行时

按现象缩小范围，再修改对应文件。

从可运行课程开始

Lua 课程使用 Forge Library：读取输入、点击保存、更新计数并恢复名称。C++ 只管理窗口与引擎；所有业务反馈都能在 Lua 源码中找到。

• Lua 实战课 →
• 下载 Lua 工程 →