WebBuilder 组件Wb.Grid 数据表格组件深入剖析

引言

在企业级应用中，数据表格是使用频率最高的组件，没有之一。WebBuilder 把表格能力沉淀为 Wb.Grid 组件族，配合 Wb.View、Wb.Column、行内编辑器与工具栏组件，形成了一套从展示、编辑、分页到数据同步的完整方案。本文基于平台示例模块 wb/modules/test/grid.xwl、wb/modules/example/crud/staff.xwl 及工作流示例，剖析 Grid 的设计与用法。

Grid 的类族与定位

WebBuilder 客户端控件库（wb/js/wb-client.min.js）中，视图类组件的继承体系为：Wb.Component → Wb.View → Wb.Grid。与 Grid 平级的有 Wb.Tree、Wb.ListView，它们共享视图层的分页、数据加载与选中模型。Grid 的元数据注册在 wb/system/controls.json 中，包含 properties、events、cname 三张表，IDE 据此在可视化设计器中生成属性面板，这也是"所见即所得"配置表格的基础。

一个最小的 Grid 页面

三个关键点：其一，url 指向数据加载接口，通常用 @xpath + '/data' 指向同模块内的数据子模块；其二，editable: 'true' 开启行内编辑；其三，工具栏按钮通过 app.grid1.addRecord() 等 Grid 内置方法驱动增删改。对应的 data.xwl 数据模块极其精简：

Wb.sendSql 查询数据库并输出 Grid 约定的 JSON 结构（{items, columns, fields, total}），前端 Grid 即可自动渲染列与分页。这种"数据模块 + 表格模块"的分离，是 WebBuilder CRUD 开发的标准姿势。

列定义与行内编辑器

列通过 isProperty: 'true' 的 Wb.Column 子节点声明，每个列可指定数据字段、标题、宽度、渲染格式等。开启可编辑后，列可以内嵌编辑器控件——在工作流报销示例 example/workflow/reimburse/start-form.xwl 中，可以看到 Wb.Column 下直接挂载 Wb.Date、Wb.Text、Wb.Number 作为 editor 属性节点。编辑器本身就是完整的表单控件，因此自动继承了输入校验、格式化等能力，无需另写胶水代码。

数据同步：modifiedData 与 Wb.sync

Grid 在客户端维护脏数据集。当用户增删改行记录后，grid.modifiedData 会收集所有变更；提交时通常在保存按钮事件中调用服务端方法，由服务端执行 Wb.sync：

Wb.sync 接收 {tableName, insert, update, remove} 结构，按语义分别生成 INSERT/UPDATE/DELETE 并在同一事务中执行。这个示例还展示了服务端介入数据加工的典型手法：为新增行自动补齐主键 Wb.getId()、流程 ID 与当前用户 Wb.userid。前后端职责就此清晰划分——Grid 负责采集变更，服务端负责校验、补数据与落库。

常用 API 与事件

Grid 暴露的方法覆盖了典型 CRUD 场景：addRecord() 新增行、删除选中行、getSelected() 取选中记录、刷新重载等。事件方面，view.on('success', fn) / un() 可动态订阅数据操作成功事件；配合 Wb.ajax({url:'m?xwl=path', params, json:true, success}) 也能手工提交并处理响应。搜索场景中，官方示例 search-form.xwl 展示了把表单查询参数合并进 Grid 加载请求的通用写法。

结语

Wb.Grid 的设计哲学是"声明 + 约定"：列、编辑器、工具栏全部声明式配置；数据结构遵循统一 JSON 约定；写回走 Wb.sync 通用协议。开发者真正要写的代码，只剩下业务规则本身——这正是低代码平台在组件层面应有的样子。