VOL 知识库

外观

官方文档站：**http://doc.volcore.xyz/**（VuePress，vol.pro 全量开发文档，331 个页面）

Why: 这套框架的很多用法（尤其是 ViewGrid 事件钩子、Service 重写委托）在源码里不好找，官方文档是最权威的速查来源；但站点没有 sitemap、SPA 导航抓不到，路径还有"两层同名前缀"的坑，不记下来每次都要重新试错。

How to apply: 需要某个功能怎么写时，先按下面索引定位页面，再用 http://doc.volcore.xyz<路径> 抓取正文（需要 .html 后缀）。

路径陷阱（重要） ​

  • 表格类文档在 /docs/web/table/，不在 /docs/table/。/docs/table/ 只有 api/basic/edit/format/head/params/render/search/tree 这 9 个（是 VolTable 组件参数）。直接访问 /docs/web/table/summary.html 这类才有内容；/docs/table/summary.html 是 404。
  • 站点无 sitemap.xml / robots.txt，SPA 首页抓不到导航。要拿全量路由，抓 http://doc.volcore.xyz/assets/app-Cy3e1IGo.js（hash 会随版本变），用正则 "(/[A-Za-z0-9_\-/\.]*\.html)" 提取。

文档分区 ​

分区路径内容
后端业务实现/docs/cs/service/guid(功能说明)、search(主表查询/合计/看sql)、or、detail(明细查询/合计)、add、update、del、audit(审批)、flow、antiAudit(反审)、exportData、importData、upload
后端常用功能/docs/cs/dev/api、config、appsettings、db(EF/Dapper/SqlSugar)、code(生成单据号/自增流水)、user、userauth、dic、cache、log、tenancy(租户)、task(定时任务接口)、interfaceauth、sqlBulkInsert、jointable(多表关联视图生成代码)、viewtable、util
后端数据库/docs/cs/dev/db/EFsql(原生sql/存储过程)、EFtrans(事务)、dapper、Dappertrans、dapperotherdb、SqlSugarotherdb、join(多表关联/主从明细查询)、efupdate
前端通用/docs/web/general/http(excel/pdf下载)、selectTable、selectData、selectDetailData(弹窗选单)、authBtn、customBtn、box、event、viewDetail、date、tabs、cache、tableV2(大数据量表格卡顿)、slot、openEdit
前端表格/docs/web/table/summary、merge、mergeField、sort(默认排序)、headFilter(表头筛选)、showFilter、queryFields(快捷查询字段)、removeQuery、dySearch、formatter、customCell、editTable(在线编辑)、hideColumn、page、hidePage、treeTable、qrcode、progress、rowColor、tagColor、fxColumn、cellEvent、rowClick、detailCalc(明细实时计算)、detailSelectChange、detailUpload、detailFilter
前端表单/docs/web/form/formReadonly(只读/默认值/必填)、customValidator、formCalc(实时计算)、editSelectChange、dataCascader、multipleUpload、group(分组)、right(左右结构)、subdetails(三级明细)、excelImport、continueAdd、modelEvent、dateRange、hideFormItem
ViewGrid/docs/view-grid/properties、methods(事件钩子总入口)、methods/ 下 70+ 个钩子：onInit、onInited、searchBefore/After、addBefore/After、updateBefore/After、delBefore/After、importBefore/After、exportBefore/After、printBefore、auditBefore/After、modelOpenBefore/After、rowClick、detailRowClick、sortEnd、spanMethod、getDefaultRow；common/ 下：search、add、rowData、getRowData、detailRowData、getDetailRowData、searchDetail、initDicKeys、updateDetailSummary、setFixedSearchForm
打印/docs/print/config、table、houtaidayinfangfashixian(后台打印方法实现)、zidingyidayinnarong(自定义打印内容)
表单组件/docs/form/calc、event、form、group、params

高频功能官方写法（已验证） ​

主表/明细表合计 ​

前端（vue3 写在生成的 表.vue）：

js
columns.forEach(x => { if (x.field == '字段') {
  x.summary = true;                    // 或 'avg' 求平均
  x.numberLength = 4;                  // 小数位，默认2
  x.summaryFormatter = (val, column, rows, summaryData) => { summaryData[0]='汇总'; return '￥'+val; };
}})
// 明细表：gridRef.detailOptions.columns / gridRef.details / gridRef.subDetails

后端（写在主表 Service）：

csharp
public override PageGridData<T> GetPageData(PageDataOptions options) {
    SummaryExpress = (ISugarQueryable<T> q) => q.Select(x => new {
        Qty = SqlFunc.AggregateSum(x.Qty)     // EF 版用 GroupBy(x=>1).Select(...).FirstOrDefault()
    }).FirstOrDefault();
    return base.GetPageData(options);
}
// 明细表合计：protected override object GetDetailSummary<Detail>(ISugarQueryable<Detail> queryable)

单元格合并 ​

<view-grid :spanMethod="spanMethod">，spanMethod({row,column,rowIndex,columnIndex}, rows) 返回 {rowspan, colspan}，rows 是当前页所有行。

主从表一起保存（后端） ​

在 Partial/{表}Service.cs 重写 Add(SaveModel saveDataModel)，用三个委托，base.Add 内部已开事务，return webResponse.Error(...) 或抛异常即回滚：

csharp
AddOnExecute     = (SaveModel sm) => ...;              // 实体转换前，sm.MainData/DetailData 还是字典
AddOnExecuting   = (主表 order, object list) => ...;   // list 是明细集合：list as List<当前表明细>
AddOnExecuted    = (主表 order, object list) => ...;
return base.Add(saveDataModel);

异步版：AddAsync + AddOnExecutingAsync/AddOnExecutedAsync（需代码生成器勾选"异步接口"）。

导出 ​

重写 Export(PageDataOptions)：Limit = 1000（最大导出数）、ExportColumns = x => new { x.字段1 }、ExcelHeaderMap（改标题）、ExportOnExecuting(list, ignore)、ExportCustomValue(value, field, entity, index)（自定义单元格值）。

审批 ​

重写 Audit(object[] keys, int? auditStatus, string auditReason)： AuditWorkFlowExecuting(o, status, lastAudit)、AuditWorkFlowExecuted(o, status, nextUserIds, lastAudit)；lastAudit=true 表示流程结束；回退用 base.RewriteFlow(order)；无界面节点时改用 AuditOnExecuting/Executed。末尾必须 return base.Audit(...)。

文件上传（确认无 OSS） ​

只能改本地相对路径，默认 wwwroot：

csharp
public override WebResponseContent Upload(List<IFormFile> files) {
    UploadFolder = $"test/{DateTime.Now:yyyyMMdd}";
    return base.Upload(files);
}

官方文档没有任何 OSS/云存储章节 —— 与源码里 VolUpload.vue 的 uploadOSS() 空函数互相印证：云存储必须自建。

快捷查询字段 ​

gridRef.queryFields = ['字段1','字段2']（代码生成器里必须先勾选"查询行"字段才生效）；隐藏高级查询按钮：遍历 buttons 把 name=='高级查询' 的 hidden=true。