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