DOM、事件与数据

使用方式

DOM 用于查找和更新元素，事件按捕获、目标、冒泡路径派发。焦点、hover、pointer capture 和拖放会影响输入路由；嵌套控件需验证事件目标和传播行为。

接入和限制

修改内容后让正常帧更新样式和布局。读取几何可能触发同步更新，不要在循环里交替写样式和读几何。数据模型保留在业务层，更新 DOM 的时机和对象生命期应由应用管理。

读取表单当前状态

读取 HTMLInputElement::value() 与 isChecked()；使用 setValue() 和 setChecked() 更新控件。value/checked 属性和当前状态存在区别，不能用属性读取代替所有用户输入状态。

cpp

    auto* name = dynamic_cast<kui::HTMLInputElement*>(doc->getElementById("display-name"));
    auto* notifications = dynamic_cast<kui::HTMLInputElement*>(doc->getElementById("notifications"));
    auto* save = doc->getElementById("save");
    auto* reset = doc->getElementById("reset");
    auto* status = doc->getElementById("status");
    auto* revision = doc->getElementById("revision");
    if (!name || !notifications || !save || !reset || !status || !revision) return 2;

原生保存事件

addEventListener 返回监听器编号，可用 removeEventListener 移除。回调引用的元素属于当前文档；文档重载会使旧元素引用失效，必须重新取得并绑定。

cpp

    save->addEventListener("click", [&](kui::Event&) {
        // value() 是当前输入；value 属性是初始值，两者不能混用。
        if (!state.save(name->value(), notifications->isChecked())) {
            name->setAttribute("aria-invalid", "true");
            status->setAttribute("data-state", "error");
            status->setTextContent(english ? "Enter a display name (up to 256 UTF-8 bytes)."
                                         : "请输入显示名称（最多 256 个 UTF-8 字节）。");
            return;
        }
        name->removeAttribute("aria-invalid");
        status->setAttribute("data-state", "success");
        status->setTextContent((english ? "Saved in this session: " : "本次会话已保存：") + state.name);
        revision->setTextContent(std::to_string(state.revision));
    });

事件课程

一个保存按钮的完整链路

UI 回调应能解释“读到了什么、保存了什么、失败后留下什么”。

加载页面后查找元素，检查节点存在且类型正确。
点击时读取 value()/isChecked() 的当前值，而不是初始属性。
交给模型校验；失败不覆盖原有数据，成功再更新模型。
用 setTextContent 显示反馈，按结果设置状态属性。
单独测试恢复、空白输入、长文本和连续点击。

避免重复绑定和错误捕获

初始化函数重复执行可能导致一次点击保存两次。把绑定集中在页面建立阶段；页面重建时建立新的绑定。回调捕获的模型必须比回调活得更久，不能引用已经退出的局部作用域。

文档有误或遗漏？

反馈此页问题 →