表单与组件

使用方式

表单、按钮、输入、选择与弹出层由 KUI 组件与 DOM 行为共同组成。实际键盘导航、输入法、焦点和无障碍支持需按目标平台检查。自定义外观时保留可见焦点和状态区别。

接入和限制

长列表可使用 VirtualList，选择列表可用 ListView，树结构可用 TreeView。它们通过可见行复用减少 DOM 数量，业务数据与行实例分开管理；动态改变数据后按组件约定通知更新。

输入框和复选框

本工程采用原生 HTML 表单元素，C++ 持有数据模型。名称校验失败保留原有数据；恢复操作只改变当前控件状态。通知选项不连接系统通知服务。

• 下载设置页工程 →

VirtualList、ListView 与 TreeView

VirtualList 管理可见行和滚动范围；ListView 增加选择与激活；TreeView 维护树的展开、折叠和可见节点投影。业务数据保留在宿主模型中，行实例只呈现当前可见内容。

• 虚拟列表接口 →
• 树视图接口 →

创建可选择的列表

容器需要明确可用高度。示例生成 1000 条演示数据，配置固定行高和单选模式，并选择第一行。这是 API 用法示例，不是性能跑分。ListView 对象应覆盖它所绑定容器的使用期。

void configureList(kui::ListView& list, kui::Element* container) {
    kui::ListViewConfig config;
    config.itemCount = 1000;
    config.itemHeight = 36;
    config.selectionMode = kui::ListViewConfig::Single;
    config.itemProvider = [](kui::u32 index) {
        kui::ListViewItem item;
        item.text = "Item " + std::to_string(index + 1);
        return item;
    };
    list.setup(container, config);
    list.select(0);
}

更新数据与行内容

数量变化使用 setItemCount，已有项的显示内容变化使用 refresh。不要只修改数据数组后期待旧行自动重绘。固定行高时优先使用统一 itemHeight；可变行高需要维护额外的高度映射。

list.setItemCount(1200);
list.refresh();
list.scrollToIndex(100);
list.clearSelection();

• 列表组件示例 →

普通 DOM 还是虚拟列表

几个按钮和短列表直接用 DOM 更简单。大量同构行使用 VirtualList，选择或激活行为可选 ListView，树形关系使用 TreeView。不要为了虚拟化把每条业务数据永久绑到一个行节点。

虚拟组件接入排查

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

跟做一万条数据的工作台

课程把数据生成、可见行渲染、选择、跳转和详情面板连起来。10,000 是示例数据量，不是性能结论；用 DevTools 查看实际渲染行数。

• 虚拟列表课程 →
• 下载工作台 →