JQuick-Excel 導(dǎo)出圖表使用規(guī)范面向 Java 開發(fā)者的 JQuick-Excel 圖表導(dǎo)出規(guī)范說明。本文聚焦EXPORT WITH GRAPH {...}的 DSL 配置、適用邊界、代碼約束與最佳實踐。更多示例: JQuick-Excel 官網(wǎng)示例 https://www.jquick.org/jquick-excel/#demo-formulas00051. 適用范圍JQuick-Excel 當(dāng)前支持通過 DSL 方式直接導(dǎo)出 Excel 圖表底層基于 Apache POI XSSF / XDDF 實現(xiàn)。當(dāng)前支持的圖表類型類型編碼圖表名稱典型場景COLUMN柱狀圖分類對比、銷售額對比BAR條形圖排名展示、橫向比較BAR3D3D 條形圖強(qiáng)展示場景LINE折線圖趨勢分析PIE餅圖占比分析AREA面積圖累積趨勢AREA3D3D 面積圖強(qiáng)展示場景SCATTER散點圖相關(guān)性分析RADAR雷達(dá)圖多維能力評估SURFACE曲面圖三維矩陣數(shù)據(jù)2. 基本設(shè)計原則圖表導(dǎo)出和普通表格導(dǎo)出不同GRAPH 是“圖表驅(qū)動”而不是“數(shù)據(jù)表驅(qū)動”。也就是說MAPPING/FORMAT/TRANSFORM主要作用于表格單元格導(dǎo)出GRAPH使用的是獨立圖表數(shù)據(jù)模型TYPE、TITLE、CATEGORIES、SERIES圖表數(shù)據(jù)不會自動從ListMapString,Object中推導(dǎo)必須在 DSL 中顯式聲明建議把 GRAPH 理解為一段聲明式圖表配置 一組內(nèi)嵌類別/序列數(shù)據(jù) - 生成 Excel 圖表 Sheet3. DSL 規(guī)范3.1 標(biāo)準(zhǔn)結(jié)構(gòu)EXPORT WITH GRAPH { TYPE COLUMN, TITLE 銷售數(shù)據(jù)統(tǒng)計, CATEGORY_AXIS 產(chǎn)品, VALUE_AXIS 銷量, CATEGORIES [產(chǎn)品A, 產(chǎn)品B, 產(chǎn)品C, 產(chǎn)品D], SERIES [ { NAME 第一季度, DATA [120, 200, 150, 180] }, { NAME 第二季度, DATA [180, 210, 190, 220] } ] }3.2 字段說明字段是否必填類型說明TYPE是枚舉圖表類型TITLE是String圖表標(biāo)題CATEGORY_AXIS否String分類軸標(biāo)題常用于 X 軸VALUE_AXIS否String數(shù)值軸標(biāo)題常用于 Y 軸CATEGORIES是Array分類集合SERIES是Array數(shù)據(jù)系列集合SERIES[].NAME是String/Identifier系列名稱SERIES[].DATA是Array系列數(shù)值集合4. 數(shù)據(jù)約束這是程序員最需要關(guān)注的部分。4.1CATEGORIES.size()必須與每個SERIES.DATA.size()一致圖表工廠內(nèi)部使用第一列寫CATEGORIES后續(xù)列逐個寫每個SERIES然后根據(jù)單元格區(qū)域創(chuàng)建圖表數(shù)據(jù)源因此必須滿足每個系列的數(shù)據(jù)點數(shù)量 分類數(shù)量正確示例CATEGORIES [Q1, Q2, Q3, Q4], SERIES [{ NAME 產(chǎn)品A, DATA [100, 120, 130, 150] }]錯誤示例CATEGORIES [Q1, Q2, Q3, Q4], SERIES [{ NAME 產(chǎn)品A, DATA [100, 120] }]后者會導(dǎo)致圖表數(shù)據(jù)區(qū)域不匹配表現(xiàn)為圖表數(shù)據(jù)缺失圖表顯示異常某些類型下直接生成錯誤圖表4.2SERIES至少要有一組SERIES []這種配置沒有業(yè)務(wù)意義也不應(yīng)該用于生產(chǎn)環(huán)境。建議規(guī)范SERIES.size() 1每個SERIES.DATA.size() 14.3DATA中應(yīng)全部為數(shù)值推薦使用intlongdoubleBigDecimal對應(yīng)的數(shù)值字面量不推薦文本數(shù)字如120帶單位字符串如120萬空字符串 / null4.4PIE圖建議只放一組系列雖然底層接口允許按統(tǒng)一模型傳入多組SERIES但從業(yè)務(wù)語義上餅圖通常應(yīng)只有1 個系列CATEGORIES表示扇區(qū)名稱DATA表示每個扇區(qū)值推薦寫法TYPE PIE, CATEGORIES [Apple, Samsung, Xiaomi, Other], SERIES [{ NAME 市場份額, DATA [38.5, 22.3, 15.7, 23.5] }]5. 各圖表類型使用建議5.1COLUMN適用于同維度多系列對比。TYPE COLUMN, TITLE 銷售數(shù)據(jù)統(tǒng)計, CATEGORY_AXIS 產(chǎn)品, VALUE_AXIS 銷量推薦場景產(chǎn)品銷量對比班級成績對比部門人力規(guī)模對比5.2BAR適用于排名型數(shù)據(jù)尤其分類名較長時優(yōu)于COLUMN。推薦場景季度銷售排行城市 GDP 排名TopN 指標(biāo)橫向比較5.3LINE適用于時間序列 / 趨勢分析。推薦場景月度溫度變化訂單趨勢活躍用戶增長曲線5.4PIE適用于單組占比。不適合類別過多多系列并列比較時間趨勢分析5.5AREA/AREA3D適用于累積型趨勢展示強(qiáng)調(diào)面積感。5.6SCATTER適用于二維相關(guān)性分析。例如身高 / 體重價格 / 銷量CPU 使用率 / 響應(yīng)時間5.7RADAR適用于多維能力評估每組對象在多個維度下對比。5.8SURFACE適用于三維矩陣型數(shù)據(jù)。這是當(dāng)前最不適合普通業(yè)務(wù)報表的圖表類型建議僅在明確有三維展示訴求時使用。6. Java 調(diào)用方式6.1 最小可用示例Stringrule EXPORT WITH GRAPH { TYPE COLUMN, TITLE 銷售數(shù)據(jù)統(tǒng)計, CATEGORY_AXIS 產(chǎn)品, VALUE_AXIS 銷量, CATEGORIES [產(chǎn)品A, 產(chǎn)品B, 產(chǎn)品C, 產(chǎn)品D], SERIES [{ NAME 第一季度, DATA [120, 200, 150, 180] }, { NAME 第二季度, DATA [180, 210, 190, 220] }] } ;JQuickExcelCommonExportExecutorexecutornewJQuickExcelCommonExportExecutor();JExcelExportModelconfig(JExcelExportModel)executor.execute(rule);JExcelExportHandlerhandlernewJExcelExportHandler(config,newArrayList());try(FileOutputStreamoutnewFileOutputStream(D://test//column.xlsx)){handler.getWorkBook().write(out);}6.2 推薦調(diào)用姿勢如果只是導(dǎo)出圖表數(shù)據(jù)行可傳空集合new ArrayList()只通過GRAPH生成獨立圖表工作表如果要同時導(dǎo)出表格和圖表當(dāng)前更適合拆成兩份導(dǎo)出邏輯一份專門生成表格一份專門生成圖表原因見第 8 節(jié)。7. 底層行為說明7.1 圖表實際寫入的是一個新 Sheet當(dāng)前實現(xiàn)里圖表工廠會workbook.createSheet(sheetName)把CATEGORIES SERIES先寫到這個 sheet在這個 sheet 上創(chuàng)建 drawing / anchor / chart所以圖表不是附著在已有業(yè)務(wù)表格的指定區(qū)域上TITLE同時也會被用作 sheetName 傳入圖表工廠若標(biāo)題重復(fù)可能引發(fā)工作表重名問題7.2 GRAPH 會觸發(fā)“禁用流式導(dǎo)出”圖表導(dǎo)出需要回頭訪問 workbook 中已寫入內(nèi)容并創(chuàng)建圖表錨點因此會觸發(fā)needsRandomRowAccess(config)從而禁用 SXSSF 流式導(dǎo)出。這意味著即使全局開啟了流式導(dǎo)出只要配置了GRAPH當(dāng)前導(dǎo)出也會降級為XSSFWorkbook對程序員的含義是GRAPH 不適合超大數(shù)據(jù)量導(dǎo)出主鏈路。建議圖表導(dǎo)出用于匯總結(jié)果頁、統(tǒng)計頁大批量明細(xì)數(shù)據(jù)導(dǎo)出與圖表導(dǎo)出分離8. 使用邊界與限制8.1 當(dāng)前圖表數(shù)據(jù)來源不是業(yè)務(wù)表格區(qū)域引用當(dāng)前實現(xiàn)是先把 DSL 中的CATEGORIES、SERIES.DATA寫到圖表 sheet 中再基于寫入后的區(qū)域創(chuàng)建圖表這意味著當(dāng)前不支持從已有 Excel 數(shù)據(jù)區(qū)域自動綁定圖表直接引用業(yè)務(wù) sheet 某一列作為圖表數(shù)據(jù)源在同一個業(yè)務(wù) sheet 指定任意位置插圖表8.2 不適合復(fù)雜圖表布局當(dāng)前沒有 DSL 字段可以控制圖表顯示位置圖表大小多圖排版圖例位置數(shù)據(jù)標(biāo)簽顏色主題次坐標(biāo)軸組合圖柱線混合圖所以這套 GRAPH 更適合快速生成標(biāo)準(zhǔn)報表圖自動化導(dǎo)出中的基礎(chǔ)統(tǒng)計展示而不適合高定制 BI 報表PPT 級視覺排版復(fù)雜 dashboard8.3TITLE建議唯一由于當(dāng)前會把標(biāo)題作為 sheetName 傳入圖表創(chuàng)建邏輯因此建議同一個 workbook 中每個圖表標(biāo)題保持唯一避免同名圖表導(dǎo)致 sheetName 沖突不推薦TITLE 統(tǒng)計圖推薦TITLE 2025年第一季度銷售統(tǒng)計圖9. 推薦規(guī)范9.1 DSL 編寫規(guī)范建議統(tǒng)一風(fēng)格EXPORT WITH GRAPH { TYPE COLUMN, TITLE 銷售數(shù)據(jù)統(tǒng)計, CATEGORY_AXIS 產(chǎn)品, VALUE_AXIS 銷量, CATEGORIES [產(chǎn)品A, 產(chǎn)品B, 產(chǎn)品C], SERIES [{ NAME 第一季度, DATA [120, 200, 150] }] }規(guī)范要求TYPE使用大寫枚舉值TITLE、CATEGORY_AXIS、VALUE_AXIS使用引號包裹CATEGORIES明確按展示順序?qū)懭隨ERIES中DATA長度必須與CATEGORIES保持一致業(yè)務(wù)上沒有意義時不要使用 3D 圖9.2 業(yè)務(wù)建模規(guī)范在程序?qū)咏ㄗh先做圖表 DTO再拼 DSL不要直接在 Controller 層硬編碼字符串。推薦模型classChartRequest{Stringtype;Stringtitle;StringcategoryAxis;StringvalueAxis;ListStringcategories;ListSeriesRequestseries;}classSeriesRequest{Stringname;ListNumberdata;}這樣好處是便于參數(shù)校驗便于單元測試便于后續(xù)擴(kuò)展圖表模板9.3 導(dǎo)出前校驗規(guī)范在執(zhí)行executor.execute(rule)前建議先做以下校驗type非空且屬于支持列表title非空categories非空series非空每個series.name非空每個series.data非空所有series.data.size()與categories.size()相同10. 常見錯誤清單錯誤 1分類數(shù)量和數(shù)據(jù)點數(shù)量不一致CATEGORIES [Q1, Q2, Q3], SERIES [{ NAME 產(chǎn)品A, DATA [120, 130] }]錯誤 2餅圖傳多組系列TYPE PIE, SERIES [{...}, {...}]雖然 DSL 可能可解析但業(yè)務(wù)上通常不合理。錯誤 3把 GRAPH 當(dāng)成表格圖表綁定器錯誤理解先導(dǎo)出表格再讓 GRAPH 自動引用表格列生成圖表。當(dāng)前不是這個模式。錯誤 4大數(shù)據(jù)量場景仍強(qiáng)依賴 GRAPH圖表會禁用流式導(dǎo)出不適合海量明細(xì)導(dǎo)出主流程。錯誤 5圖表標(biāo)題過于泛化TITLE 圖表可能帶來 sheetName 沖突也不利于后續(xù)維護(hù)。11. 推薦模板11.1 柱狀圖模板EXPORT WITH GRAPH { TYPE COLUMN, TITLE 年度銷售統(tǒng)計, CATEGORY_AXIS 產(chǎn)品, VALUE_AXIS 銷量, CATEGORIES [產(chǎn)品A, 產(chǎn)品B, 產(chǎn)品C, 產(chǎn)品D], SERIES [{ NAME 2025, DATA [120, 200, 150, 180] }] }11.2 折線圖模板EXPORT WITH GRAPH { TYPE LINE, TITLE 月度訪問趨勢, CATEGORY_AXIS 月份, VALUE_AXIS 訪問量, CATEGORIES [1月, 2月, 3月, 4月], SERIES [{ NAME 官網(wǎng), DATA [1000, 1200, 1150, 1500] }, { NAME 小程序, DATA [800, 900, 980, 1300] }] }11.3 餅圖模板EXPORT WITH GRAPH { TYPE PIE, TITLE 渠道占比, CATEGORIES [官網(wǎng), 小程序, App, 線下], SERIES [{ NAME 占比, DATA [35, 25, 20, 20] }] }11.4 雷達(dá)圖模板EXPORT WITH GRAPH { TYPE RADAR, TITLE 工程師能力評估, CATEGORIES [編碼, 設(shè)計, 溝通, 測試, 學(xué)習(xí)], SERIES [{ NAME 張三, DATA [90, 85, 75, 80, 95] }, { NAME 李四, DATA [80, 88, 82, 78, 85] }] }12. 最佳實踐總結(jié)推薦用COLUMN / BAR / LINE / PIE解決 80% 報表圖需求導(dǎo)出前先做數(shù)據(jù)長度一致性校驗圖表導(dǎo)出和大批量明細(xì)導(dǎo)出分離保持TITLE唯一且可讀在服務(wù)層先構(gòu)建圖表 DTO再拼 DSL不推薦在 Controller 直接手寫復(fù)雜 GRAPH DSL在一個超大導(dǎo)出任務(wù)里混用 GRAPH依賴 GRAPH 自動綁定已有表格區(qū)域給PIE、RADAR配置不合理的多系列結(jié)構(gòu)使用含義不明確的標(biāo)題和類別值13. 一句話結(jié)論如果你站在程序員角度使用 JQuick-Excel 的圖表能力最重要的認(rèn)知是GRAPH 是一套“聲明式圖表數(shù)據(jù)模型”適合生成標(biāo)準(zhǔn)化統(tǒng)計圖它不是 BI 畫布也不是對已有表格區(qū)域的自動綁定器。因此最佳用法是先在業(yè)務(wù)層整理好 categories series再用 DSL 生成標(biāo)準(zhǔn)圖表導(dǎo)出。