JQuick-Excel 實(shí)戰(zhàn)以 TRANSFORM、上下文與 FOOTER 組織導(dǎo)出渲染tags: Java, Excel, JQuick-Excel, 模板渲染, TRANSFORM, FOOTER, XML DSL更多示例: JQuick-Excel 官網(wǎng)示例 https://www.jquick.org/jquick-excel/#demo-formulas0005簡(jiǎn)介“Excel 模板渲染”容易被誤解為拿一份任意現(xiàn)成的 xlsx在單元格中放置某種占位符然后由框架替換。就本項(xiàng)目 README-CN 與src/test/resources/jquick-excel.xml可確認(rèn)的內(nèi)容而言可靠的導(dǎo)出渲染能力是EXPORT WITH下的字段映射、TRANSFORM、FORMAT、STYLE、主題和FOOTER。README-CN 明確寫出使用TRANSFORM、上下文值和FOOTER表達(dá)式根據(jù)業(yè)務(wù)數(shù)據(jù)渲染輸出測(cè)試 XML 也展示了字典轉(zhuǎn)換、數(shù)值轉(zhuǎn)換和日期轉(zhuǎn)換。本文嚴(yán)格限定在這些證據(jù)內(nèi)。文中的“模板”指 XML 中可版本化的導(dǎo)出規(guī)則與主題配置不編造外部 xlsx 單元格占位符語(yǔ)法不假定未知的模板加載 API也不把FOOTER說(shuō)成打印設(shè)置中的頁(yè)眉頁(yè)腳。FOOTER的已確認(rèn) DSL 是FOOTERGenerated by JQuickExcelREADME-CN 還展示了FOOTERGenerated by JQuickExcel on ${current_date()}。是否使用表達(dá)式取決于當(dāng)前依賴和函數(shù)是否已確認(rèn)可用。前言導(dǎo)出文件的內(nèi)容經(jīng)常需要經(jīng)過(guò)展示層處理。業(yè)務(wù)對(duì)象中性別可能保存為編碼日期可能需要統(tǒng)一顯示姓名可能需要文本轉(zhuǎn)換文件末尾還需要寫明生成來(lái)源或日期。把這些規(guī)則散落在 Java 組裝代碼中會(huì)使數(shù)據(jù)準(zhǔn)備和報(bào)表展示耦合。JQuick-Excel 的 XML DSL 可以把字段到表頭的映射、字段轉(zhuǎn)換、顯示格式、樣式和頁(yè)腳集中在一個(gè)導(dǎo)出定義中讓規(guī)則成為可審查的資源。README-CN 給出了導(dǎo)出配置的職責(zé)劃分MAPPING將源字段映射到表頭TRANSFORM在輸出前轉(zhuǎn)換值FORMAT定義 Excel 顯示格式STYLE對(duì)目標(biāo)應(yīng)用樣式FOOTER設(shè)置頁(yè)腳文本。測(cè)試 XML 中的實(shí)際配置是gender:trans(${dict},${gender})、age:add(${age},1)、enrollmentDate:dateFormat(${enrollmentDate},yyyy-MM-dd)。這說(shuō)明渲染不是未知的字符串替換而是針對(duì)當(dāng)前行字段和上下文的 DSL 表達(dá)式計(jì)算。上下文使同一規(guī)則可以使用外部字典等值。README-CN 明確JContext可保存字典${field}讀取當(dāng)前行字段${key}可讀取JContext值。于是trans(${dict},${gender})可以把當(dāng)前行的gender交給dict翻譯。這里的規(guī)則方向應(yīng)由輸出目的決定導(dǎo)出通常是從內(nèi)部編碼變成展示文字導(dǎo)入校驗(yàn)中的dict規(guī)則則是另一種輸入成員關(guān)系約束不應(yīng)混淆。環(huán)境與依賴本文使用 Java 8 和 JQuick-Excel3.6.0。README-CN 明確支持xls、xlsx并公開(kāi) Maven 依賴坐標(biāo)。dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-excel/artifactIdversion3.6.0/version/dependencyXML 規(guī)則放在類路徑中通過(guò)namespace與服務(wù)接口關(guān)聯(lián)。以下片段采用 README-CN 的結(jié)構(gòu)EXPORT WITH指定表頭和映射TRANSFORM處理展示值FORMAT管理 Excel 日期顯示FOOTER寫出收尾文本。?xml version1.0 encodingUTF-8?!DOCTYPEexcelsPUBLIC-//PAOHAIJIAO//DTD API EXCEL 1.0//ENclasspath:paohaijiao/dtd/Jquick-excel.dtdexcelsnamespacecom.example.excel.StudentReportServiceexcelnameexportStudentReportreturnClassvoid![CDATA[ EXPORT WITH SHEET學(xué)生報(bào)表, HEADERtrue, MAPPING{ id:主鍵, name:姓名, gender:性別, enrollmentDate:入學(xué)時(shí)間 }, FORMAT{enrollmentDate:yyyy-MM-dd}, TRANSFORM{ name:toUpper(${name}), gender:trans(${dict},${gender}) }, FOOTERGenerated by JQuickExcel ]]/excel/excels上例中的toUpper與trans都來(lái)自 README-CN 已列出的內(nèi)置求值器。FORMAT并不取代TRANSFORM前者是最終 Excel 顯示格式后者是字段表達(dá)式計(jì)算。頁(yè)腳使用固定文本因而不會(huì)依賴當(dāng)前上下文是否存在某個(gè)函數(shù)。代碼示例Java 側(cè)先準(zhǔn)備字典并放入JContext。README-CN 已給出context.put(dict, gender)并明確導(dǎo)入解析器接收上下文和輸入流對(duì)于導(dǎo)出README-CN 同樣說(shuō)明 Java 調(diào)用方提供業(yè)務(wù)數(shù)據(jù)、流和上下文值。下例展示已確認(rèn)的上下文構(gòu)造方式。importcom.github.paohaijiao.context.JContext;importjava.util.HashMap;importjava.util.Map;MapString,ObjectgendernewHashMap();gender.put(1,Male);gender.put(0,Female);JContextcontextnewJContext();context.put(dict,gender);數(shù)據(jù)準(zhǔn)備和 XML 導(dǎo)出調(diào)用可沿用 README-CN 的基礎(chǔ)入口。行數(shù)據(jù)通過(guò)JObjectConverter轉(zhuǎn)換再由JQuickRow.toRows組織輸出流和行數(shù)據(jù)傳入JQuickExcelExportXmlParseFactoryXML 工廠創(chuàng)建服務(wù)代理。下例沒(méi)有編造將JContext注入導(dǎo)出解析器的未知構(gòu)造方式仍使用 README-CN 明確展示的導(dǎo)出構(gòu)造形式上下文相關(guān)能力應(yīng)在項(xiàng)目實(shí)際已確認(rèn)的調(diào)用封裝中提供。importcom.github.paohaijiao.convert.JObjectConverter;importcom.github.paohaijiao.statement.JQuickRow;importcom.github.paohaijiao.xml.JQuickFactory;importcom.github.paohaijiao.xml.JQuickXmlFactory;importcom.github.paohaijiao.xml.parse.JQuickParseHandler;importcom.github.paohaijiao.xml.parse.excel.JQuickExcelExportXmlParseFactory;importjava.io.FileOutputStream;importjava.io.OutputStream;importjava.util.List;importjava.util.Map;ListMapString,ObjectstudentsloadStudents();ListJQuickRowrowsJQuickRow.toRows(JObjectConverter.convert(students));try(OutputStreamoutputnewFileOutputStream(students.xlsx)){JQuickParseHandlerparsernewJQuickExcelExportXmlParseFactory(rows,output);JQuickFactoryfactorynewJQuickXmlFactory(parser,jquick-excel.xml);StudentReportServiceservicefactory.createApi(StudentReportService.class);service.exportStudentReport(field,value);}項(xiàng)目測(cè)試 XML 還給出了一個(gè)更完整的轉(zhuǎn)換組合。以下規(guī)則只復(fù)用測(cè)試資源中實(shí)際出現(xiàn)的字段與函數(shù)形式性別使用trans年齡使用add入學(xué)日期使用dateFormat。該片段用于說(shuō)明測(cè)試中存在的 DSL并不要求每份報(bào)表都進(jìn)行年齡加一或日期文本轉(zhuǎn)換。excelnameexportExcelreturnClassvoid![CDATA[ EXPORT WITH SHEET學(xué)生表, HEADERtrue, MAPPING{ id:主鍵, name:姓名, gender:性別, age:年齡, enrollmentDate:入學(xué)時(shí)間 }, TRANSFORM{ gender:trans(${dict},${gender}), age:add(${age},1), enrollmentDate:dateFormat(${enrollmentDate},yyyy-MM-dd) }, FOOTERGenerated by JQuickExcel ]]/excelREADME-CN 還展示頁(yè)腳表達(dá)式形式。只有在當(dāng)前項(xiàng)目確認(rèn)表達(dá)式函數(shù)可用時(shí)才應(yīng)采用這種寫法本文不把它擴(kuò)展為外部 xlsx 的占位符語(yǔ)法。它仍然是 XML DSL 中FOOTER的值。excelnameexportReportreturnClassvoid![CDATA[ EXPORT WITH SHEETReport, HEADERtrue, MAPPING{name:Name,gender:Gender}, TRANSFORM{gender:trans(${dict},${gender})}, FOOTERGenerated by JQuickExcel on ${current_date()} ]]/excel主題也是 README-CN 確認(rèn)的導(dǎo)出能力。文檔列出 42 個(gè)內(nèi)置主題并展示在執(zhí)行規(guī)則后、創(chuàng)建導(dǎo)出處理器前通過(guò)JExcelExportModel設(shè)置主題的示例。以下 Java 代碼僅復(fù)用 README-CN 已給出的類、調(diào)用順序與主題設(shè)置方式。JExcelExportModelconfig(JExcelExportModel)executor.execute(rule);config.setTheme(jade);JExcelExportHandlerhandlernewJExcelExportHandler(config,data);Workbookworkbookhandler.getWorkBook();workbook.write(outputStream);主題、TRANSFORM、FORMAT和FOOTER可以共同組成一份配置驅(qū)動(dòng)的導(dǎo)出規(guī)則主題統(tǒng)一視覺(jué)基調(diào)映射決定列轉(zhuǎn)換決定展示值格式?jīng)Q定 Excel 單元格顯示頁(yè)腳補(bǔ)充收尾文本。但這不等于框架已經(jīng)公開(kāi)支持讀取任意 xlsx 并掃描替換其中的占位符。沒(méi)有可執(zhí)行證據(jù)時(shí)應(yīng)將需求限制為已確認(rèn) DSL或另行補(bǔ)充專用模板能力的驗(yàn)證。原理說(shuō)明README-CN 描述的運(yùn)行鏈路是當(dāng)前行字段或JContext值通過(guò)${field}進(jìn)入TRANSFORM表達(dá)式函數(shù)查找后調(diào)用提供者得到轉(zhuǎn)換結(jié)果最終由FORMAT控制 Excel 顯示。內(nèi)置求值器包含toUpper、dateFormat、trans。項(xiàng)目測(cè)試 XML 中實(shí)際使用了trans、add、dateFormat可作為當(dāng)前項(xiàng)目配置示例的證據(jù)。MAPPING在這條鏈路中負(fù)責(zé)字段到表頭的映射。README-CN 的導(dǎo)出示例為MAPPING{id:ID,name:Name}即左側(cè)是數(shù)據(jù)源字段、右側(cè)是輸出列頭。TRANSFORM仍以左側(cè)字段為目標(biāo)例如gender:trans(${dict},${gender})FORMAT同樣以字段為鍵例如enrollmentDate:yyyy-MM-dd。這三個(gè)配置應(yīng)保持字段鍵一致避免因重命名 DTO 屬性或調(diào)整數(shù)據(jù)轉(zhuǎn)換層而產(chǎn)生靜默偏差。JContext是外部值容器。README-CN 的示例創(chuàng)建字典后調(diào)用context.put(dict, gender)表達(dá)式再通過(guò)${dict}取用。當(dāng)前行字段和上下文鍵有不同來(lái)源${gender}是行字段${dict}是上下文。編寫trans(${dict},${gender})時(shí)應(yīng)明確字典中的鍵和值對(duì)應(yīng)什么展示方向并用真實(shí)數(shù)據(jù)驗(yàn)證編碼和顯示文字是否一致。FOOTER是導(dǎo)出 DSL 的一個(gè)獨(dú)立參數(shù)。README-CN 給出固定文本FOOTERGenerated by JQuickExcel也給出帶${current_date()}的文本表達(dá)式并說(shuō)明它可渲染文本或變量表達(dá)式。因此最穩(wěn)妥的默認(rèn)方式是固定文本使用表達(dá)式時(shí)先確認(rèn)當(dāng)前版本和依賴中相應(yīng)函數(shù)已可用。不能把 DSL 文本中的${...}推導(dǎo)為任意 xlsx 單元格都可替換的語(yǔ)法。主題則是模型層面的導(dǎo)出視覺(jué)配置。README-CN 的例子是在解析規(guī)則獲得JExcelExportModel后調(diào)用config.setTheme(jade)再創(chuàng)建JExcelExportHandler和工作簿。主題 code 應(yīng)來(lái)自 README-CN 列出的內(nèi)置名稱例如default、jade、oceanBlue、royalGold等。主題不改變MAPPING、TRANSFORM或FOOTER的業(yè)務(wù)含義它只服務(wù)于已確認(rèn)的導(dǎo)出視覺(jué)主題設(shè)置。注意事項(xiàng)第一不要編造外部 xlsx 占位符語(yǔ)法。README-CN 和測(cè)試 XML 證明的是 XML DSL 中的${field}、${key}、TRANSFORM、FOOTER表達(dá)式和主題設(shè)置而不是“在任意 xlsx 單元格寫${name}即會(huì)替換”。遇到這種需求應(yīng)先補(bǔ)充可執(zhí)行證據(jù)或采用已驗(yàn)證的專用方案。第二TRANSFORM與FORMAT不可混淆。值確實(shí)需要翻譯、大寫或日期格式化時(shí)使用TRANSFORM僅需要 Excel 顯示日期或數(shù)字時(shí)使用FORMAT。同一字段同時(shí)在多處反復(fù)承擔(dān)顯示職責(zé)會(huì)降低規(guī)則可讀性。第三字典方向必須以輸出目標(biāo)為準(zhǔn)。trans(${dict},${gender})讀取上下文字典和當(dāng)前行字段字典內(nèi)容應(yīng)從內(nèi)部值映射到用戶要看到的文字。導(dǎo)入中的dict校驗(yàn)規(guī)則屬于另一個(gè)問(wèn)題不能不經(jīng)檢查地復(fù)用同一映射方向。第四頁(yè)腳文本是報(bào)表內(nèi)容的一部分。若報(bào)表還需要合計(jì)、公式或合并區(qū)域應(yīng)在設(shè)計(jì)時(shí)明確它們與FOOTER的順序并用真實(shí)文件驗(yàn)證最終布局。本文只確認(rèn)FOOTER的 DSL 文本能力不假定未公開(kāi)的打印頁(yè)眉頁(yè)腳行為。第五主題 code 使用 README-CN 已列出的名稱。拼寫、依賴版本和實(shí)際輸出效果均應(yīng)在目標(biāo)環(huán)境驗(yàn)證。主題是視覺(jué)選擇不應(yīng)隱藏字段口徑、審核狀態(tài)或其他必須以數(shù)據(jù)列明確表達(dá)的業(yè)務(wù)信息。第六流、數(shù)據(jù)和上下文的生命周期應(yīng)由調(diào)用端明確管理。README-CN 的導(dǎo)出示例使用 try-with-resources 關(guān)閉輸出流導(dǎo)入示例在輸入流打開(kāi)期間執(zhí)行代理調(diào)用。實(shí)際工程應(yīng)沿用該資源管理原則而不要依賴未確認(rèn)的自動(dòng)關(guān)閉行為?？偨Y(jié)這里的“模板渲染”應(yīng)落在已經(jīng)確認(rèn)的 XML 導(dǎo)出規(guī)則上MAPPING決定列與表頭TRANSFORM基于當(dāng)前行和JContext計(jì)算展示值FORMAT管理單元格顯示主題處理統(tǒng)一視覺(jué)FOOTER補(bǔ)充收尾文本。它的優(yōu)點(diǎn)是配置可版本化、規(guī)則可審查真正需要變化的是字段展示或報(bào)表布局時(shí)應(yīng)先定位到對(duì)應(yīng)配置項(xiàng)而不是把處理散進(jìn)數(shù)據(jù)組裝代碼。字典轉(zhuǎn)換是最需要驗(yàn)證方向的一環(huán)。${gender}是當(dāng)前行字段${dict}是上下文值trans(${dict},${gender})的結(jié)果應(yīng)以真實(shí)編碼和展示文字核對(duì)。頁(yè)腳使用固定文本最容易保持確定性采用${current_date()}一類表達(dá)式前應(yīng)確認(rèn)當(dāng)前版本和依賴中函數(shù)可用。主題也只改變外觀不能取代報(bào)表中需要明確呈現(xiàn)的業(yè)務(wù)字段。使用邊界必須清晰已有證據(jù)支持 DSL 內(nèi)的表達(dá)式取值與FOOTER文本不支持據(jù)此推導(dǎo)任意外部 xlsx 單元格占位符都會(huì)被掃描替換。復(fù)雜模板需求應(yīng)先補(bǔ)充可執(zhí)行驗(yàn)證。導(dǎo)出驗(yàn)收則應(yīng)同時(shí)檢查轉(zhuǎn)換結(jié)果、日期與數(shù)字顯示、頁(yè)腳位置和主題效果并確保輸出流、行數(shù)據(jù)及上下文在執(zhí)行期間都由調(diào)用端按明確生命周期管理。