view-grid 与 vol-form、vol-table 组件关系
view-grid 与 vol-form、vol-table 组件关系
文档定位
- view-grid：生成页总控 — 生命周期 Hook（
onInit、searchBefore、addBefore…）、页面属性、Slots、公共方法。 - vol-form / vol-table：view-grid 内部渲染查询区、编辑表单、主表、明细表；字段级事件绑定在 options 配置对象上完成。
- docs/form、docs/table：组件完整 API（独立页面或非生成页场景）；生成页业务 优先 在
{表}.vue的onInit+ view-grid 文档中实现。
1. 内部结构（ViewGrid.vue）
view-grid
├── vol-form ref="searchForm" ← searchFormFields / searchFormOptions（查询区）
├── vol-table ref="table" ← columns（主表列表）
└── 编辑弹框 (vol-box)
├── vol-form ref="form" ← editFormFields / editFormOptions（主表编辑）
└── vol-table ref="detail" ← detail.columns / detailOptions（明细，一对多另有 details[]）
生成页 {表}.vue 把 options.js 里的字段/列配置 Props 传给 view-grid，view-grid 再透传给内嵌的 vol-form、vol-table。
2. 配置与组件对照
| view-grid 属性 | 内嵌组件 | 说明 |
|---|---|---|
searchFormFields / searchFormOptions | 查询 vol-form | 查询条件；规则同 vol-form 的 formFields / formRules |
editFormFields / editFormOptions | 编辑 vol-form | 弹框主表表单 |
columns | 主表 vol-table | 列表列；列事件见下表 |
detail / detailOptions | 明细 vol-table | 主从明细；detailOptions.columns 同 vol-table columns |
details[] | 多个 vol-table | 一对多明细 Tab |
字段 type、bind、validator 等 与 vol-form / vol-table 一致，详见 vol-form 参数、vol-table 参数。
3. 三层扩展方式（由外到内）
| 层级 | 做什么 | 在哪写 | 文档 |
|---|---|---|---|
| ① ViewGrid Hook | 查询/保存/删除/审批前后；行点击；明细加载 | {表}.vue 绑定 :searchBefore、:addBefore… | methods/ |
| ② gridRef 配置 | 改 columns、editFormOptions、按钮、高度等 | onInit / onInited 里 gridRef.xxx = | properties.md |
| ③ 字段/列事件 | 回车、onChange、blur、formatter、单元格 click | getFormOption / columns / detailOptions.columns | event/ · [§12.E Skill] |
原则： 能放在 Hook 层（如保存前校验）优先 Hook；纯 UI 联动、实时计算用 ③ 字段事件；复杂交互 Recipe 见 web 前端开发。
4. 字段与列事件绑定（生成页标准写法）
在 {表}.vue 的 onInit 中，gridRef = $vm 后：
4.1 编辑表单（内嵌 vol-form）
// 方式一：推荐
gridRef.getFormOption('Qty').onChange = (val) => {
editFormFields.Amount = val * editFormFields.Price
}
gridRef.getFormOption('Qty').onKeyPress = ($event) => { /* 回车 */ }
gridRef.getFormOption('Qty').blur = () => {}
// 方式二：遍历 editFormOptions（options.js 来的二维数组）
editFormOptions.flat().find(o => o.field === 'Qty').onChange = (val) => { ... }
// 查询表单：getSearchFormOption('字段').onChange = ...
文档：forminput · formchange · formblur · formfocus · formcalc
4.2 主表列表（内嵌 vol-table）
gridRef.columns.forEach(c => {
if (c.field === 'OrderNo') {
c.formatter = (row) => row.OrderNo
c.click = (row, column, event) => { /* 单元格点击 */ }
}
})
行级 Hook 用 view-grid 的 :rowClick、:beginEdit 等，见 methods/rowClick.md。
4.3 明细表（内嵌 vol-table）
在 onInited 中配置（字典加载后）：
gridRef.detailOptions.columns.forEach(c => {
if (c.field === 'Qty') {
c.onKeyPress = (row, column, $event) => { row.Amount = row.Qty * row.Price }
c.onChange = (row, val) => { }
c.blur = (row, column, $event) => { }
c.formatter = (row) => row.Qty * row.Price // 显示用计算
c.checkEdit = (row, column, index) => true // 是否可编辑
}
})
文档：detailforminput · detailformchange · detailformcalc
5. 访问内嵌组件 ref
| 需求 | 写法 |
|---|---|
| 主表 table 实例 | gridRef.getTable() 或 gridRef.$refs.table |
| 明细 table | gridRef.getTable() / 一对多 gridRef.getTable('明细表名') |
| 编辑表单 | gridRef.$refs.form |
| 查询表单 | gridRef.$refs.searchForm |
| 字段 DOM 焦点 | gridRef.$refs.form.$refs.字段名[0].focus()（见 formfocus 文档） |
| 明细行数据 | gridRef.getTable().rowData |
| 刷新合计 | gridRef.getTable().updateSummary('字段') |
6. 文档查阅路由（AI / 开发）
| 需求类型 | 先查 | 细节补查 |
|---|---|---|
| searchBefore / addBefore 等页面流程 | view-grid methods | — |
| 表单字段 onChange / 回车 | view-grid event/ | web/form 示例 |
| 明细列编辑 / 计算 | view-grid event/detail* | web/table/detailCalc |
| vol-form 独有 props（labelWidth、group…） | — | docs/form/ |
| vol-table 独有 props（tableV2、merge…） | view-grid properties | docs/table/ |
| 弹框选数、自定义按钮等效果 | — | docs/web/ |
7. 新页面编辑（Edit.vue）
Edit.vue 使用 vol-edit，内部同样组合 vol-form + vol-table，Hook 名不同（loadFormBefore、loadTableBefore…），字段事件仍在 onInit 里改 editFormOptions / detail.columns。见 edit 文档。