From 42937204775d272bdbfc7d17591cfeed39a5f43d Mon Sep 17 00:00:00 2001 From: liuhy Date: Mon, 9 Nov 2026 19:49:02 -0800 Subject: [PATCH] feat: preserve native tables during template filling Signed-off-by: liuhy --- .../executor/ExcelWriteFillExecutor.java | 27 +- .../handler/DefaultWriteHandlerLoader.java | 2 + .../impl/StructuredTableFormulaShifter.java | 189 +++++ .../StructuredTableWorkbookWriteHandler.java | 263 +++++++ .../sheet/fill/StructuredTableFillTest.java | 660 ++++++++++++++++++ website/docs/sheet/fill/fill.md | 38 + .../current/sheet/fill/fill.md | 27 + 7 files changed, 1202 insertions(+), 4 deletions(-) create mode 100644 fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableFormulaShifter.java create mode 100644 fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableWorkbookWriteHandler.java create mode 100644 fesod-sheet/src/test/java/org/apache/fesod/sheet/fill/StructuredTableFillTest.java diff --git a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/executor/ExcelWriteFillExecutor.java b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/executor/ExcelWriteFillExecutor.java index fb743c8f13..de4ab54c97 100644 --- a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/executor/ExcelWriteFillExecutor.java +++ b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/executor/ExcelWriteFillExecutor.java @@ -57,6 +57,7 @@ import org.apache.fesod.sheet.util.WriteHandlerUtils; import org.apache.fesod.sheet.write.handler.context.CellWriteHandlerContext; import org.apache.fesod.sheet.write.handler.context.RowWriteHandlerContext; +import org.apache.fesod.sheet.write.handler.impl.StructuredTableWorkbookWriteHandler; import org.apache.fesod.sheet.write.metadata.fill.AnalysisCell; import org.apache.fesod.sheet.write.metadata.fill.FillConfig; import org.apache.fesod.sheet.write.metadata.fill.FillWrapper; @@ -66,6 +67,7 @@ import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.usermodel.Row; import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.xssf.usermodel.XSSFSheet; /** * Fill the data into excel @@ -108,8 +110,15 @@ public class ExcelWriteFillExecutor extends AbstractExcelWriteExecutor { */ private UniqueDataFlagKey currentUniqueDataFlag; + private final StructuredTableWorkbookWriteHandler structuredTableHandler; + public ExcelWriteFillExecutor(WriteContext writeContext) { super(writeContext); + structuredTableHandler = writeContext.writeWorkbookHolder().getWriteHandlerList().stream() + .filter(StructuredTableWorkbookWriteHandler.class::isInstance) + .map(StructuredTableWorkbookWriteHandler.class::cast) + .findFirst() + .orElse(null); } public void fill(Object data, FillConfig fillConfig) { @@ -142,6 +151,15 @@ public void fill(Object data, FillConfig fillConfig) { if (CollectionUtils.isEmpty(collectionData)) { return; } + Sheet cachedSheet = writeContext.writeSheetHolder().getCachedSheet(); + if (structuredTableHandler != null && cachedSheet instanceof XSSFSheet) { + structuredTableHandler.prepareFill( + (XSSFSheet) cachedSheet, + analysisCellList, + collectionLastIndexCache.get(currentUniqueDataFlag), + fillConfig, + collectionData.size()); + } Iterator iterator = collectionData.iterator(); if (WriteDirectionEnum.VERTICAL.equals(fillConfig.getDirection()) && fillConfig.getForceNewRow()) { shiftRows(collectionData.size(), analysisCellList); @@ -176,9 +194,6 @@ private void shiftRows(int size, List analysisCellList) { } Sheet cachedSheet = writeContext.writeSheetHolder().getCachedSheet(); int lastRowIndex = cachedSheet.getLastRowNum(); - if (maxRowIndex >= lastRowIndex) { - return; - } Sheet sheet = writeContext.writeSheetHolder().getCachedSheet(); int number = size; if (collectionLastIndexMap == null) { @@ -187,7 +202,11 @@ private void shiftRows(int size, List analysisCellList) { if (number <= 0) { return; } - sheet.shiftRows(maxRowIndex + 1, lastRowIndex, number, true, false); + if (structuredTableHandler != null && sheet instanceof XSSFSheet) { + structuredTableHandler.shiftRows((XSSFSheet) sheet, maxRowIndex, lastRowIndex, number); + } else if (maxRowIndex < lastRowIndex) { + sheet.shiftRows(maxRowIndex + 1, lastRowIndex, number, true, false); + } // The current data is greater than unity rowindex increase increaseRowIndex(templateAnalysisCache, number, maxRowIndex); diff --git a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/DefaultWriteHandlerLoader.java b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/DefaultWriteHandlerLoader.java index 924282ca04..86538ab0c0 100644 --- a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/DefaultWriteHandlerLoader.java +++ b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/DefaultWriteHandlerLoader.java @@ -32,6 +32,7 @@ import org.apache.fesod.sheet.write.handler.impl.DimensionWorkbookWriteHandler; import org.apache.fesod.sheet.write.handler.impl.EscapeHexCellWriteHandler; import org.apache.fesod.sheet.write.handler.impl.FillStyleCellWriteHandler; +import org.apache.fesod.sheet.write.handler.impl.StructuredTableWorkbookWriteHandler; import org.apache.fesod.sheet.write.handler.impl.WriteSheetWorkbookWriteHandler; import org.apache.fesod.sheet.write.style.DefaultStyle; @@ -59,6 +60,7 @@ public static List loadDefaultHandler(Boolean useDefaultStyle, Exc List handlerList = new ArrayList<>(); switch (excelType) { case XLSX: + handlerList.add(new StructuredTableWorkbookWriteHandler()); handlerList.add(new DimensionWorkbookWriteHandler()); handlerList.add(new DefaultRowWriteHandler()); handlerList.add(new EscapeHexCellWriteHandler()); diff --git a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableFormulaShifter.java b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableFormulaShifter.java new file mode 100644 index 0000000000..c3c704dec0 --- /dev/null +++ b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableFormulaShifter.java @@ -0,0 +1,189 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.apache.fesod.sheet.write.handler.impl; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.IdentityHashMap; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.TreeSet; +import org.apache.fesod.sheet.exception.ExcelGenerateException; +import org.apache.poi.ss.formula.FormulaParser; +import org.apache.poi.ss.formula.FormulaRenderer; +import org.apache.poi.ss.formula.FormulaShifter; +import org.apache.poi.ss.formula.FormulaType; +import org.apache.poi.ss.formula.ptg.Ptg; +import org.apache.poi.ss.usermodel.Cell; +import org.apache.poi.ss.usermodel.CellType; +import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.ss.util.CellRangeAddress; +import org.apache.poi.xssf.usermodel.XSSFCell; +import org.apache.poi.xssf.usermodel.XSSFEvaluationWorkbook; +import org.apache.poi.xssf.usermodel.XSSFSheet; +import org.apache.poi.xssf.usermodel.XSSFTable; +import org.apache.poi.xssf.usermodel.XSSFWorkbook; + +final class StructuredTableFormulaShifter { + private StructuredTableFormulaShifter() {} + + static Map shiftFormulas( + XSSFSheet movedSheet, int firstRow, int lastRow, int number, Map ranges) { + XSSFWorkbook workbook = movedSheet.getWorkbook(); + FormulaShifter shifter = FormulaShifter.createForRowShift( + workbook.getSheetIndex(movedSheet), + movedSheet.getSheetName(), + firstRow, + lastRow, + number, + workbook.getSpreadsheetVersion()); + XSSFEvaluationWorkbook evaluationWorkbook = XSSFEvaluationWorkbook.create(workbook); + Set names = new TreeSet<>(String.CASE_INSENSITIVE_ORDER); + for (Sheet sheet : workbook) { + for (XSSFTable table : ((XSSFSheet) sheet).getTables()) { + if (table.getName() != null) { + names.add(table.getName()); + } + } + } + if (names.isEmpty()) { + return Collections.emptyMap(); + } + Map formulas = new IdentityHashMap<>(); + for (Sheet sheet : workbook) { + for (Row row : sheet) { + for (Cell cell : row) { + if (cell.getCellType() != CellType.FORMULA + || !cell.getCellFormula().contains("[")) { + continue; + } + String shifted = shiftFormula((XSSFCell) cell, names, shifter, evaluationWorkbook, ranges); + if (shifted != null) { + formulas.put((XSSFCell) cell, shifted); + } + } + } + } + return formulas; + } + + private static String shiftFormula( + XSSFCell cell, + Set names, + FormulaShifter shifter, + XSSFEvaluationWorkbook workbook, + Map ranges) { + String formula = cell.getCellFormula(); + String marker = "__fesod_table_reference_"; + while (formula.contains(marker)) { + marker += "_"; + } + List references = new ArrayList<>(); + StringBuilder masked = new StringBuilder(); + int copied = 0; + for (int index = 0; index < formula.length(); index++) { + char current = formula.charAt(index); + if (current == '"' || current == '\'') { + while (++index < formula.length()) { + if (formula.charAt(index) == current) { + if (index + 1 < formula.length() && formula.charAt(index + 1) == current) { + index++; + } else { + break; + } + } + } + } else if (current == '[') { + int start = index; + while (start > copied && isNameCharacter(formula.charAt(start - 1))) { + start--; + } + boolean qualified = names.contains(formula.substring(start, index)); + boolean local = start == index && insideTable(cell, ranges); + if (!qualified && !local) { + continue; + } + int depth = 1; + int end = index + 1; + for (; end < formula.length() && depth > 0; end++) { + char character = formula.charAt(end); + if (character == '\'') { + end++; + } else if (character == '[') { + depth++; + } else if (character == ']') { + depth--; + } + } + if (depth != 0) { + throw new ExcelGenerateException("Unbalanced structured table reference: " + formula); + } + if (!qualified + && end < formula.length() + && (isNameCharacter(formula.charAt(end)) || formula.charAt(end) == '!')) { + continue; + } + masked.append(formula, copied, start) + .append('"') + .append(marker) + .append(references.size()) + .append('"'); + references.add(formula.substring(start, end)); + copied = end; + index = end - 1; + } + } + if (references.isEmpty()) { + return null; + } + masked.append(formula, copied, formula.length()); + int sheetIndex = cell.getSheet().getWorkbook().getSheetIndex(cell.getSheet()); + // Mask only table expressions so POI can move A1 references without expanding tables into A1 ranges. + Ptg[] tokens = + FormulaParser.parse(masked.toString(), workbook, FormulaType.CELL, sheetIndex, cell.getRowIndex()); + if (!shifter.adjustFormula(tokens, sheetIndex)) { + return formula; + } + String shifted = FormulaRenderer.toFormulaString(workbook, tokens); + for (int index = 0; index < references.size(); index++) { + shifted = shifted.replace('"' + marker + index + '"', references.get(index)); + } + return shifted; + } + + private static boolean isNameCharacter(char character) { + return Character.isLetterOrDigit(character) || character == '_' || character == '.' || character == '\\'; + } + + private static boolean insideTable(XSSFCell cell, Map ranges) { + for (XSSFTable table : cell.getSheet().getTables()) { + CellRangeAddress range = ranges.get(table); + if (range == null) { + range = CellRangeAddress.valueOf(table.getCTTable().getRef()); + } + if (range.isInRange(cell.getRowIndex(), cell.getColumnIndex())) { + return true; + } + } + return false; + } +} diff --git a/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableWorkbookWriteHandler.java b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableWorkbookWriteHandler.java new file mode 100644 index 0000000000..37b352bb6e --- /dev/null +++ b/fesod-sheet/src/main/java/org/apache/fesod/sheet/write/handler/impl/StructuredTableWorkbookWriteHandler.java @@ -0,0 +1,263 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.apache.fesod.sheet.write.handler.impl; + +import java.util.Collections; +import java.util.IdentityHashMap; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.TreeSet; +import org.apache.fesod.sheet.enums.WriteDirectionEnum; +import org.apache.fesod.sheet.exception.ExcelGenerateException; +import org.apache.fesod.sheet.write.handler.WorkbookWriteHandler; +import org.apache.fesod.sheet.write.metadata.fill.AnalysisCell; +import org.apache.fesod.sheet.write.metadata.fill.FillConfig; +import org.apache.fesod.sheet.write.metadata.holder.WriteWorkbookHolder; +import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.ss.util.AreaReference; +import org.apache.poi.ss.util.CellRangeAddress; +import org.apache.poi.ss.util.CellReference; +import org.apache.poi.xssf.usermodel.XSSFCell; +import org.apache.poi.xssf.usermodel.XSSFSheet; +import org.apache.poi.xssf.usermodel.XSSFTable; + +/** + * Tracks template table layout during collection fills and applies it before workbook serialization. + */ +public class StructuredTableWorkbookWriteHandler implements WorkbookWriteHandler { + private final Map ranges = new IdentityHashMap<>(); + private final Set growingTables = Collections.newSetFromMap(new IdentityHashMap<>()); + + public void prepareFill( + XSSFSheet sheet, + List cells, + Map lastIndexes, + FillConfig config, + int size) { + growingTables.clear(); + if (cells == null) { + return; + } + validateNames(sheet); + boolean vertical = config.getDirection() == WriteDirectionEnum.VERTICAL; + Map updated = new IdentityHashMap<>(); + for (XSSFTable table : sheet.getTables()) { + CellRangeAddress range = currentRange(table).copy(); + int lastDataRow = range.getLastRow() - table.getTotalsRowCount(); + for (AnalysisCell cell : cells) { + int row = cell.getRowIndex(); + int column = cell.getColumnIndex(); + Integer previous = lastIndexes == null ? null : lastIndexes.get(cell); + if (vertical) { + if (column < range.getFirstColumn() || column > range.getLastColumn()) { + continue; + } + int first = previous == null ? row : previous + 1; + int last = first + size - 1; + require( + last >= first + && last + <= sheet.getWorkbook() + .getSpreadsheetVersion() + .getLastRowIndex(), + table, + "The fill cannot extend beyond the last worksheet row."); + if (config.getForceNewRow()) { + if (row >= range.getFirstRow() && row <= range.getLastRow()) { + require( + row > range.getFirstRow() && row <= lastDataRow, + table, + "Collection placeholders must be in the table's data rows."); + growingTables.add(table); + } + } else { + require( + first > range.getFirstRow() || last < range.getFirstRow(), + table, + "A collection fill cannot overwrite a table header."); + if (row > range.getFirstRow() && row <= lastDataRow) { + require( + table.getTotalsRowCount() == 0 || last <= lastDataRow, + table, + "Use forceNewRow(true) to expand a table with a totals row."); + range.setLastRow(Math.max(range.getLastRow(), last)); + } else { + require( + last < range.getFirstRow() || first > range.getLastRow(), + table, + "A collection fill cannot overwrite an unrelated table."); + } + } + } else if (row >= range.getFirstRow() && row <= range.getLastRow()) { + int first = previous == null ? column : previous + 1; + int last = first + size - 1; + require( + last >= first + && last + <= sheet.getWorkbook() + .getSpreadsheetVersion() + .getLastColumnIndex(), + table, + "The fill cannot extend beyond the last worksheet column."); + if ((column >= range.getFirstColumn() && column <= range.getLastColumn()) + || (first <= range.getLastColumn() && last >= range.getFirstColumn())) { + require( + row > range.getFirstRow() && row <= lastDataRow, + table, + "A horizontal fill cannot overwrite table headers or totals."); + require( + first >= range.getFirstColumn() && last <= range.getLastColumn(), + table, + "Horizontal expansion of structured tables is not supported."); + } + } + } + validate(table, range); + updated.put(table, range); + } + validateOverlaps(sheet, updated); + ranges.putAll(updated); + } + + public void shiftRows(XSSFSheet sheet, int afterRow, int lastRow, int number) { + Map updated = new IdentityHashMap<>(); + for (XSSFTable table : sheet.getTables()) { + CellRangeAddress range = currentRange(table).copy(); + if (range.getFirstRow() > afterRow) { + range.setFirstRow(range.getFirstRow() + number); + range.setLastRow(range.getLastRow() + number); + } else if (range.getLastRow() > afterRow + || (range.getLastRow() == afterRow && growingTables.contains(table))) { + range.setLastRow(range.getLastRow() + number); + } + validate(table, range); + updated.put(table, range); + } + validateOverlaps(sheet, updated); + if (afterRow < lastRow) { + Map formulas = + StructuredTableFormulaShifter.shiftFormulas(sheet, afterRow + 1, lastRow, number, ranges); + Map originals = new IdentityHashMap<>(); + for (Map.Entry formula : formulas.entrySet()) { + XSSFCell cell = formula.getKey(); + originals.put(cell, cell.getCTCell().getF().getStringValue()); + cell.getCTCell().getF().setStringValue("0"); + } + boolean shifted = false; + try { + sheet.shiftRows(afterRow + 1, lastRow, number, true, false); + shifted = true; + } finally { + Map restored = shifted ? formulas : originals; + for (Map.Entry formula : restored.entrySet()) { + formula.getKey().getCTCell().getF().setStringValue(formula.getValue()); + } + } + } + ranges.putAll(updated); + } + + @Override + public void afterWorkbookDispose(WriteWorkbookHolder holder) { + for (Map.Entry entry : ranges.entrySet()) { + XSSFTable table = entry.getKey(); + CellRangeAddress range = entry.getValue(); + validate(table, range); + table.setCellReferences(new AreaReference( + new CellReference(range.getFirstRow(), range.getFirstColumn()), + new CellReference(range.getLastRow(), range.getLastColumn()), + table.getXSSFSheet().getWorkbook().getSpreadsheetVersion())); + table.getXSSFSheet().getWorkbook().setForceFormulaRecalculation(true); + } + } + + private CellRangeAddress currentRange(XSSFTable table) { + CellRangeAddress range = ranges.get(table); + return range == null ? originalRange(table) : range; + } + + private CellRangeAddress originalRange(XSSFTable table) { + require(table.getCTTable().getRef() != null, table, "The table has no cell range."); + CellRangeAddress range = CellRangeAddress.valueOf(table.getCTTable().getRef()); + validate(table, range); + return range; + } + + private void validate(XSSFTable table, CellRangeAddress range) { + require( + table.getHeaderRowCount() == 1 && table.getTotalsRowCount() >= 0 && table.getTotalsRowCount() <= 1, + table, + "Only tables with one header row and at most one totals row are supported."); + require( + range.getLastRow() - range.getFirstRow() >= 1 + table.getTotalsRowCount(), + table, + "The table must retain a data row between its header and totals."); + require( + range.getLastRow() + <= table.getXSSFSheet() + .getWorkbook() + .getSpreadsheetVersion() + .getLastRowIndex(), + table, + "The table cannot extend beyond the last worksheet row."); + require( + range.getLastColumn() - range.getFirstColumn() + 1 == table.getColumnCount() + && table.getColumnCount() + == table.getCTTable().getTableColumns().sizeOfTableColumnArray(), + table, + "The table range and column metadata have different widths."); + } + + private void validateNames(XSSFSheet sheet) { + Set names = new TreeSet<>(String.CASE_INSENSITIVE_ORDER); + Set displayNames = new TreeSet<>(String.CASE_INSENSITIVE_ORDER); + for (Sheet workbookSheet : sheet.getWorkbook()) { + for (XSSFTable table : ((XSSFSheet) workbookSheet).getTables()) { + require( + table.getName() != null + && names.add(table.getName()) + && table.getDisplayName() != null + && displayNames.add(table.getDisplayName()), + table, + "Table names and display names must be unique within the workbook."); + } + } + } + + private void validateOverlaps(XSSFSheet sheet, Map updated) { + List tables = sheet.getTables(); + for (int first = 0; first < tables.size(); first++) { + for (int second = first + 1; second < tables.size(); second++) { + CellRangeAddress left = updated.get(tables.get(first)); + CellRangeAddress right = updated.get(tables.get(second)); + if (left != null && right != null) { + require(!left.intersects(right), tables.get(first), "The fill would overlap another table."); + } + } + } + } + + private static void require(boolean valid, XSSFTable table, String message) { + if (!valid) { + throw new ExcelGenerateException("Structured table '" + table.getName() + "': " + message); + } + } +} diff --git a/fesod-sheet/src/test/java/org/apache/fesod/sheet/fill/StructuredTableFillTest.java b/fesod-sheet/src/test/java/org/apache/fesod/sheet/fill/StructuredTableFillTest.java new file mode 100644 index 0000000000..99485b0df1 --- /dev/null +++ b/fesod-sheet/src/test/java/org/apache/fesod/sheet/fill/StructuredTableFillTest.java @@ -0,0 +1,660 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.apache.fesod.sheet.fill; + +import java.io.File; +import java.io.FileOutputStream; +import java.util.Arrays; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import org.apache.fesod.sheet.ExcelWriter; +import org.apache.fesod.sheet.FesodSheet; +import org.apache.fesod.sheet.enums.WriteDirectionEnum; +import org.apache.fesod.sheet.exception.ExcelGenerateException; +import org.apache.fesod.sheet.testkit.Tags; +import org.apache.fesod.sheet.testkit.base.AbstractExcelTest; +import org.apache.fesod.sheet.testkit.enums.ExcelFormat; +import org.apache.fesod.sheet.write.handler.WorkbookWriteHandler; +import org.apache.fesod.sheet.write.handler.impl.StructuredTableWorkbookWriteHandler; +import org.apache.fesod.sheet.write.metadata.WriteSheet; +import org.apache.fesod.sheet.write.metadata.fill.FillConfig; +import org.apache.fesod.sheet.write.metadata.holder.WriteWorkbookHolder; +import org.apache.poi.ss.SpreadsheetVersion; +import org.apache.poi.ss.util.AreaReference; +import org.apache.poi.ss.util.CellReference; +import org.apache.poi.xssf.usermodel.XSSFSheet; +import org.apache.poi.xssf.usermodel.XSSFTable; +import org.apache.poi.xssf.usermodel.XSSFWorkbook; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; +import org.mockito.Mockito; +import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTTableColumn; +import org.openxmlformats.schemas.spreadsheetml.x2006.main.STTotalsRowFunction; + +@Tag(Tags.ROUND_TRIP) +class StructuredTableFillTest extends AbstractExcelTest { + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void expandsTableAtLastPhysicalRowAcrossRepeatedFills(boolean inMemory) throws Exception { + for (boolean forceNewRow : new boolean[] {false, true}) { + File source = template(false, false); + File output = createTempFile("table-fill", ExcelFormat.XLSX); + fill(source, output, inMemory, forceNewRow); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + XSSFSheet sheet = workbook.getSheet("Data"); + XSSFTable table = sheet.getTables().get(0); + assertTable(table, "A1:C4", "A1:C4"); + Assertions.assertEquals("third", sheet.getRow(3).getCell(0).getStringCellValue()); + Assertions.assertEquals( + "TableStyleMedium2", + table.getCTTable().getTableStyleInfo().getName()); + Assertions.assertTrue(table.getCTTable().getTableStyleInfo().getShowRowStripes()); + Assertions.assertEquals("Orders", table.getName()); + Assertions.assertEquals("Orders", table.getDisplayName()); + Assertions.assertEquals("Amount", table.getColumns().get(2).getName()); + Assertions.assertEquals( + "Orders[[#This Row],[Quantity]]*2", + table.getCTTable() + .getTableColumns() + .getTableColumnArray(2) + .getCalculatedColumnFormula() + .getStringValue()); + Assertions.assertEquals( + "SUM(Orders[Quantity])", + workbook.getSheet("Summary").getRow(0).getCell(0).getCellFormula()); + } + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void expandsBeforeTotalsAndShiftsTablesBelowWithoutChangingOtherSheets(boolean inMemory) throws Exception { + File source = template(true, true); + File output = createTempFile("table-totals", ExcelFormat.XLSX); + fill(source, output, inMemory, true); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + XSSFSheet sheet = workbook.getSheet("Data"); + XSSFTable table = sheet.getTables().get(0); + assertTable(table, "A1:C5", "A1:C4"); + Assertions.assertEquals(1, table.getTotalsRowCount()); + Assertions.assertEquals("Totals", sheet.getRow(4).getCell(0).getStringCellValue()); + CTTableColumn amount = table.getCTTable().getTableColumns().getTableColumnArray(2); + Assertions.assertEquals(STTotalsRowFunction.SUM, amount.getTotalsRowFunction()); + Assertions.assertEquals( + "SUBTOTAL(109,Orders[Amount])", sheet.getRow(4).getCell(2).getCellFormula()); + assertTable(sheet.getTables().get(1), "A10:C11", "A10:C11"); + Assertions.assertEquals("unchanged", sheet.getRow(10).getCell(0).getStringCellValue()); + assertTable(workbook.getSheet("Other").getTables().get(0), "A1:C2", "A1:C2"); + Assertions.assertEquals( + "SUM(Orders[Quantity])", + workbook.getSheet("Summary").getRow(0).getCell(0).getCellFormula()); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void keepsTablesUnchangedForAnEmptyCollection(boolean inMemory) throws Exception { + File source = template(true, true); + File output = createTempFile("table-empty", ExcelFormat.XLSX); + FesodSheet.write(output) + .withTemplate(source) + .inMemory(inMemory) + .sheet("Data") + .doFill( + Collections.emptyList(), + FillConfig.builder().forceNewRow(true).build()); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + assertTable(workbook.getSheet("Data").getTables().get(0), "A1:C3", "A1:C2"); + assertTable(workbook.getSheet("Data").getTables().get(1), "A8:C9", "A8:C9"); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void shiftsA1ReferencesWithoutReplacingStructuredReferenceSyntax(boolean inMemory) throws Exception { + File source = template(false, true); + File modified = createTempFile("table-mixed-formulas", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + XSSFSheet summary = workbook.getSheet("Summary"); + summary.getRow(0).getCell(0).setCellFormula("SUM(Orders[Quantity])+Data!B9"); + summary.createRow(1).createCell(0).setCellFormula("SUM(Below[Quantity])"); + summary.createRow(2).createCell(0).setCellFormula("SUM(Orders[[#All],[Quantity]])+Data!B9"); + summary.createRow(3) + .createCell(0) + .setCellFormula("IF(\"Orders[Quantity]\"=\"Orders[Quantity]\",SUM(Orders[Quantity]),Data!B9)"); + summary.createRow(4).createCell(0).setCellFormula("SUM(orders[Quantity])+Data!B9"); + summary.createRow(5) + .createCell(0) + .setCellFormula("SUM(Orders[Quantity])+SUM(OtherOrders[Quantity])+Data!B9"); + workbook.setCellFormulaValidation(false); + workbook.getSheet("Data").getRow(8).getCell(2).setCellFormula("[@Quantity]*2"); + workbook.write(output); + } + File output = createTempFile("table-mixed-formulas-filled", ExcelFormat.XLSX); + fill(modified, output, inMemory, true); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + XSSFSheet summary = workbook.getSheet("Summary"); + Assertions.assertEquals( + "SUM(Orders[Quantity])+Data!B11", + summary.getRow(0).getCell(0).getCellFormula()); + Assertions.assertEquals( + "SUM(Below[Quantity])", summary.getRow(1).getCell(0).getCellFormula()); + Assertions.assertEquals( + "SUM(Orders[[#All],[Quantity]])+Data!B11", + summary.getRow(2).getCell(0).getCellFormula()); + Assertions.assertEquals( + "IF(\"Orders[Quantity]\"=\"Orders[Quantity]\",SUM(Orders[Quantity]),Data!B11)", + summary.getRow(3).getCell(0).getCellFormula()); + Assertions.assertEquals( + "SUM(orders[Quantity])+Data!B11", + summary.getRow(4).getCell(0).getCellFormula()); + Assertions.assertEquals( + "SUM(Orders[Quantity])+SUM(OtherOrders[Quantity])+Data!B11", + summary.getRow(5).getCell(0).getCellFormula()); + Assertions.assertEquals( + "[@Quantity]*2", + workbook.getSheet("Data").getRow(10).getCell(2).getCellFormula()); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void preservesEscapedCharactersInStructuredColumnReferences(boolean inMemory) throws Exception { + for (String[] header : + new String[][] {{"O'Brien", "O''Brien"}, {"Q]ty", "Q']ty"}, {"Q[ty", "Q'[ty"}, {"Price#", "Price'#"}}) { + File source = template(false, true); + File modified = createTempFile("table-escaped-header", ExcelFormat.XLSX); + String reference = "Orders[" + header[1] + "]"; + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + workbook.setCellFormulaValidation(false); + XSSFSheet sheet = workbook.getSheet("Data"); + sheet.getRow(0).getCell(1).setCellValue(header[0]); + sheet.getTables() + .get(0) + .getCTTable() + .getTableColumns() + .getTableColumnArray(1) + .setName(header[0]); + sheet.getTables() + .get(0) + .getCTTable() + .getTableColumns() + .getTableColumnArray(2) + .getCalculatedColumnFormula() + .setStringValue(reference + "*2"); + sheet.getRow(1).getCell(2).setCellFormula(reference + "*2"); + workbook.getSheet("Summary").getRow(0).getCell(0).setCellFormula("SUM(" + reference + ")+Data!B9"); + workbook.write(output); + } + File output = createTempFile("escaped-header-filled", ExcelFormat.XLSX); + fill(modified, output, inMemory, true); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + Assertions.assertEquals( + "SUM(" + reference + ")+Data!B11", + workbook.getSheet("Summary").getRow(0).getCell(0).getCellFormula()); + Assertions.assertEquals( + header[0], + workbook.getSheet("Data") + .getTables() + .get(0) + .getColumns() + .get(1) + .getName()); + } + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void growsOnlyTheTargetTableWhenAnotherTableIsBesideIt(boolean inMemory) throws Exception { + File source = template(false, false); + File modified = createTempFile("side-by-side-tables", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + addTable(workbook.getSheet("Data"), "Beside", 0, false, 4); + workbook.write(output); + } + File output = createTempFile("side-by-side-filled", ExcelFormat.XLSX); + fill(modified, output, inMemory, false); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + assertTable(workbook.getSheet("Data").getTables().get(0), "A1:C4", "A1:C4"); + assertTable(workbook.getSheet("Data").getTables().get(1), "E1:G2", "E1:G2"); + Assertions.assertEquals( + "unchanged", workbook.getSheet("Data").getRow(1).getCell(4).getStringCellValue()); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void expandsATableThatAlreadyHasMoreThanOneDataRow(boolean inMemory) throws Exception { + File source = template(false, false); + File modified = createTempFile("table-existing-data", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + XSSFSheet sheet = workbook.getSheet("Data"); + sheet.createRow(2).createCell(0).setCellValue("retained"); + sheet.getRow(2).createCell(1).setCellValue(10); + sheet.getRow(2).createCell(2).setCellFormula("Orders[[#This Row],[Quantity]]*2"); + sheet.getTables().get(0).setCellReferences(new AreaReference("A1:C3", SpreadsheetVersion.EXCEL2007)); + workbook.write(output); + } + File output = createTempFile("table-existing-data-filled", ExcelFormat.XLSX); + fill(modified, output, inMemory, true); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + assertTable(workbook.getSheet("Data").getTables().get(0), "A1:C5", "A1:C5"); + Assertions.assertEquals( + "retained", workbook.getSheet("Data").getRow(4).getCell(0).getStringCellValue()); + Assertions.assertEquals( + "SUM(Orders[Quantity])", + workbook.getSheet("Summary").getRow(0).getCell(0).getCellFormula()); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void preservesCustomTotalsAndLabelOnlyTotals(boolean inMemory) throws Exception { + for (boolean customFormula : new boolean[] {false, true}) { + File source = template(true, false); + File modified = createTempFile("table-custom-totals", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + XSSFSheet sheet = workbook.getSheet("Data"); + CTTableColumn column = + sheet.getTables().get(0).getCTTable().getTableColumns().getTableColumnArray(2); + if (customFormula) { + column.setTotalsRowFunction(STTotalsRowFunction.CUSTOM); + column.addNewTotalsRowFormula().setStringValue("SUM(Orders[Quantity])*2"); + sheet.getRow(2).getCell(2).setCellFormula("SUM(Orders[Quantity])*2"); + } else { + column.unsetTotalsRowFunction(); + sheet.getRow(2).getCell(2).setBlank(); + } + workbook.write(output); + } + File output = createTempFile("custom-totals-filled", ExcelFormat.XLSX); + fill(modified, output, inMemory, true); + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + XSSFSheet sheet = workbook.getSheet("Data"); + XSSFTable table = sheet.getTables().get(0); + assertTable(table, "A1:C5", "A1:C4"); + Assertions.assertEquals("Totals", sheet.getRow(4).getCell(0).getStringCellValue()); + Assertions.assertEquals( + "Totals", + table.getCTTable() + .getTableColumns() + .getTableColumnArray(0) + .getTotalsRowLabel()); + if (customFormula) { + Assertions.assertEquals( + "SUM(Orders[Quantity])*2", + sheet.getRow(4).getCell(2).getCellFormula()); + Assertions.assertEquals( + "SUM(Orders[Quantity])*2", + table.getCTTable() + .getTableColumns() + .getTableColumnArray(2) + .getTotalsRowFormula() + .getStringValue()); + } + } + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void rejectsOverwritingTotalsAndUnsupportedColumnExpansion(boolean inMemory) throws Exception { + File source = template(true, false); + File output = createTempFile("table-rejected", ExcelFormat.XLSX); + try (ExcelWriter writer = + FesodSheet.write(output).withTemplate(source).inMemory(inMemory).build()) { + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Arrays.asList(item("first", 1), item("second", 2)), + FesodSheet.writerSheet("Data").build())); + Assertions.assertTrue(error.getMessage().contains("forceNewRow(true)")); + } + source = template(false, false); + try (ExcelWriter writer = + FesodSheet.write(output).withTemplate(source).inMemory(inMemory).build()) { + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Arrays.asList(item("first", 1), item("second", 2), item("third", 3)), + FillConfig.builder() + .direction(WriteDirectionEnum.HORIZONTAL) + .build(), + FesodSheet.writerSheet("Data").build())); + Assertions.assertTrue(error.getMessage().contains("Horizontal expansion")); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void rejectsExpansionIntoAnotherTable(boolean inMemory) throws Exception { + File source = template(false, true); + File output = createTempFile("table-overlap", ExcelFormat.XLSX); + try (ExcelWriter writer = + FesodSheet.write(output).withTemplate(source).inMemory(inMemory).build()) { + Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Collections.nCopies(9, item("record", 1)), + FesodSheet.writerSheet("Data").build())); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void rejectsARepeatedHorizontalFillPastTheTableBoundary(boolean inMemory) throws Exception { + File source = template(false, false); + File modified = createTempFile("horizontal-table-template", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + workbook.getSheet("Data").getRow(1).getCell(1).setCellValue("fixed"); + workbook.write(output); + } + File output = createTempFile("horizontal-table-filled", ExcelFormat.XLSX); + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(modified) + .inMemory(inMemory) + .build()) { + FillConfig config = FillConfig.builder() + .direction(WriteDirectionEnum.HORIZONTAL) + .build(); + WriteSheet sheet = FesodSheet.writerSheet("Data").build(); + writer.fill(Arrays.asList(item("first", 1), item("second", 2), item("third", 3)), config, sheet); + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill(Collections.singletonList(item("fourth", 4)), config, sheet)); + Assertions.assertTrue(error.getMessage().contains("Horizontal expansion")); + } + } + + @Test + void rejectsDuplicateTableNamesBeforeFilling() throws Exception { + File source = template(false, true); + File output = createTempFile("duplicate-table-name", ExcelFormat.XLSX); + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(source) + .registerWriteHandler(new WorkbookWriteHandler() { + @Override + public void afterWorkbookCreate(WriteWorkbookHolder holder) { + XSSFWorkbook workbook = (XSSFWorkbook) holder.getCachedWorkbook(); + workbook.getSheet("Other") + .getTables() + .get(0) + .getCTTable() + .setName("Orders"); + } + }) + .build()) { + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Collections.singletonList(item("record", 1)), + FesodSheet.writerSheet("Data").build())); + Assertions.assertTrue(error.getMessage().contains("unique")); + } + } + + @Test + void rejectsShiftingATablePastTheWorksheetLimit() throws Exception { + File source = template(false, false); + File modified = createTempFile("table-at-sheet-limit", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + addTable(workbook.getSheet("Data"), "AtLimit", SpreadsheetVersion.EXCEL2007.getLastRowIndex() - 1, false); + workbook.write(output); + } + File output = createTempFile("table-beyond-sheet-limit", ExcelFormat.XLSX); + try (ExcelWriter writer = + FesodSheet.write(output).withTemplate(modified).build()) { + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Arrays.asList(item("first", 1), item("second", 2)), + FillConfig.builder().forceNewRow(true).build(), + FesodSheet.writerSheet("Data").build())); + Assertions.assertTrue(error.getMessage().contains("last worksheet row")); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void finalizesTablesAfterFillingMoreThanOneSheet(boolean inMemory) throws Exception { + File source = template(false, true); + File modified = createTempFile("multiple-table-sheets", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(source); + FileOutputStream output = new FileOutputStream(modified)) { + workbook.getSheet("Other").getRow(1).getCell(0).setCellValue("{.name}"); + workbook.getSheet("Other").getRow(1).getCell(1).setCellValue("{.quantity}"); + workbook.write(output); + } + File output = createTempFile("multiple-table-sheets-filled", ExcelFormat.XLSX); + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(modified) + .inMemory(inMemory) + .build()) { + FillConfig config = FillConfig.builder().forceNewRow(true).build(); + writer.fill( + Arrays.asList(item("first", 1), item("second", 2)), + config, + FesodSheet.writerSheet("Data").build()); + writer.fill( + Arrays.asList(item("third", 3), item("fourth", 4), item("fifth", 5)), + config, + FesodSheet.writerSheet("Other").build()); + } + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + assertTable(workbook.getSheet("Data").getTables().get(0), "A1:C3", "A1:C3"); + assertTable(workbook.getSheet("Other").getTables().get(0), "A1:C4", "A1:C4"); + Assertions.assertEquals( + "fifth", workbook.getSheet("Other").getRow(3).getCell(0).getStringCellValue()); + } + } + + @Test + void rejectsInconsistentTableColumnMetadata() throws Exception { + File source = template(false, false); + File output = createTempFile("inconsistent-table-columns", ExcelFormat.XLSX); + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(source) + .registerWriteHandler(new WorkbookWriteHandler() { + @Override + public void afterWorkbookCreate(WriteWorkbookHolder holder) { + ((XSSFWorkbook) holder.getCachedWorkbook()) + .getSheet("Data") + .getTables() + .get(0) + .getCTTable() + .getTableColumns() + .setCount(2); + } + }) + .build()) { + ExcelGenerateException error = Assertions.assertThrows( + ExcelGenerateException.class, + () -> writer.fill( + Collections.singletonList(item("record", 1)), + FesodSheet.writerSheet("Data").build())); + Assertions.assertTrue(error.getMessage().contains("different widths")); + } + } + + @Test + void restoresTableFormulasWhenPoiRejectsTheRowShift() throws Exception { + File source = template(false, false); + try (XSSFWorkbook workbook = new XSSFWorkbook(source)) { + XSSFSheet sheet = Mockito.spy(workbook.getSheet("Data")); + IllegalStateException failure = new IllegalStateException("row shift failed"); + Mockito.doThrow(failure).when(sheet).shiftRows(2, 2, 1, true, false); + StructuredTableWorkbookWriteHandler handler = new StructuredTableWorkbookWriteHandler(); + Assertions.assertSame( + failure, + Assertions.assertThrows(IllegalStateException.class, () -> handler.shiftRows(sheet, 1, 2, 1))); + Assertions.assertEquals( + "SUM(Orders[Quantity])", + workbook.getSheet("Summary").getRow(0).getCell(0).getCellFormula()); + } + } + + @Test + void fillsAPristineClonedSheetWithIndependentTablePartsAndNames() throws Exception { + File source = template(false, false); + File output = createTempFile("cloned-table", ExcelFormat.XLSX); + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(source) + .inMemory(true) + .registerWriteHandler(new WorkbookWriteHandler() { + @Override + public void afterWorkbookCreate(WriteWorkbookHolder holder) { + XSSFWorkbook workbook = (XSSFWorkbook) holder.getCachedWorkbook(); + workbook.cloneSheet(0, "Copy"); + } + }) + .build()) { + writer.fill( + Arrays.asList(item("first", 1), item("second", 2)), + FillConfig.builder().forceNewRow(true).build(), + FesodSheet.writerSheet("Copy").build()); + } + try (XSSFWorkbook workbook = new XSSFWorkbook(output)) { + XSSFTable original = workbook.getSheet("Data").getTables().get(0); + XSSFTable copy = workbook.getSheet("Copy").getTables().get(0); + assertTable(original, "A1:C2", "A1:C2"); + assertTable(copy, "A1:C3", "A1:C3"); + Assertions.assertNotEquals(original.getName(), copy.getName()); + Assertions.assertNotEquals(original.getDisplayName(), copy.getDisplayName()); + Assertions.assertNotEquals( + original.getPackagePart().getPartName(), + copy.getPackagePart().getPartName()); + Assertions.assertEquals( + copy.getName() + "[[#This Row],[Quantity]]*2", + copy.getCTTable() + .getTableColumns() + .getTableColumnArray(2) + .getCalculatedColumnFormula() + .getStringValue()); + } + } + + private void fill(File template, File output, boolean inMemory, boolean forceNewRow) { + try (ExcelWriter writer = FesodSheet.write(output) + .withTemplate(template) + .inMemory(inMemory) + .build()) { + WriteSheet sheet = FesodSheet.writerSheet("Data").build(); + FillConfig config = FillConfig.builder().forceNewRow(forceNewRow).build(); + writer.fill(Arrays.asList(item("first", 1), item("second", 2)), config, sheet); + writer.fill(Collections.singletonList(item("third", 3)), config, sheet); + } + } + + private File template(boolean totals, boolean moreTables) throws Exception { + File file = createTempFile("structured-table-template", ExcelFormat.XLSX); + try (XSSFWorkbook workbook = new XSSFWorkbook(); + FileOutputStream output = new FileOutputStream(file)) { + XSSFSheet sheet = workbook.createSheet("Data"); + XSSFTable table = addTable(sheet, "Orders", 0, totals); + sheet.getRow(1).getCell(0).setCellValue("{.name}"); + sheet.getRow(1).getCell(1).setCellValue("{.quantity}"); + table.getCTTable() + .getTableColumns() + .getTableColumnArray(2) + .addNewCalculatedColumnFormula() + .setStringValue("Orders[[#This Row],[Quantity]]*2"); + sheet.getRow(1).getCell(2).setCellFormula("Orders[[#This Row],[Quantity]]*2"); + workbook.createSheet("Summary").createRow(0).createCell(0).setCellFormula("SUM(Orders[Quantity])"); + if (moreTables) { + addTable(sheet, "Below", 7, false); + addTable(workbook.createSheet("Other"), "OtherOrders", 0, false); + } + workbook.write(output); + } + return file; + } + + private static XSSFTable addTable(XSSFSheet sheet, String name, int firstRow, boolean totals) { + return addTable(sheet, name, firstRow, totals, 0); + } + + private static XSSFTable addTable(XSSFSheet sheet, String name, int firstRow, boolean totals, int firstColumn) { + List headers = Arrays.asList("Name", "Quantity", "Amount"); + for (int row = firstRow; row <= firstRow + (totals ? 2 : 1); row++) { + if (sheet.getRow(row) == null) { + sheet.createRow(row); + } + for (int column = 0; column < headers.size(); column++) { + sheet.getRow(row).createCell(firstColumn + column); + } + } + for (int column = 0; column < headers.size(); column++) { + sheet.getRow(firstRow).getCell(firstColumn + column).setCellValue(headers.get(column)); + } + sheet.getRow(firstRow + 1).getCell(firstColumn).setCellValue("unchanged"); + XSSFTable table = sheet.createTable(new AreaReference( + new CellReference(firstRow, firstColumn), + new CellReference(firstRow + (totals ? 2 : 1), firstColumn + 2), + SpreadsheetVersion.EXCEL2007)); + table.setName(name); + table.setDisplayName(name); + table.getCTTable().addNewTableStyleInfo().setName("TableStyleMedium2"); + table.getCTTable().getTableStyleInfo().setShowRowStripes(true); + if (!table.getCTTable().isSetAutoFilter()) { + table.getCTTable().addNewAutoFilter(); + } + table.getCTTable() + .getAutoFilter() + .setRef(new AreaReference( + new CellReference(firstRow, firstColumn), + new CellReference(firstRow + 1, firstColumn + 2), + SpreadsheetVersion.EXCEL2007) + .formatAsString()); + if (totals) { + table.getCTTable().setTotalsRowCount(1); + table.getCTTable().getTableColumns().getTableColumnArray(0).setTotalsRowLabel("Totals"); + table.getCTTable().getTableColumns().getTableColumnArray(2).setTotalsRowFunction(STTotalsRowFunction.SUM); + sheet.getRow(firstRow + 2).getCell(0).setCellValue("Totals"); + sheet.getRow(firstRow + 2).getCell(2).setCellFormula("SUBTOTAL(109," + name + "[Amount])"); + } + return table; + } + + private static Map item(String name, int quantity) { + Map item = new HashMap<>(); + item.put("name", name); + item.put("quantity", quantity); + return item; + } + + private static void assertTable(XSSFTable table, String area, String filter) { + Assertions.assertEquals(area, table.getCTTable().getRef()); + Assertions.assertEquals(filter, table.getCTTable().getAutoFilter().getRef()); + } +} diff --git a/website/docs/sheet/fill/fill.md b/website/docs/sheet/fill/fill.md index 24ea99aa22..98db248bbb 100644 --- a/website/docs/sheet/fill/fill.md +++ b/website/docs/sheet/fill/fill.md @@ -49,6 +49,44 @@ Escaping stops the braces from being parsed, but the `\` characters are only rem cell also holds a real placeholder. In a cell that contains nothing else, `\{name\}` is written out exactly as typed, backslashes included. +## Native Excel Tables + +Collection fills recognize existing Excel Tables created with **Insert → Table** in an XLSX +template. These native tables are separate from Fesod's `WriteTable` API. At writer finish, +Fesod synchronizes their ranges and AutoFilter references with the filled rows, including +repeated fills and tables shifted by inserted rows. Both `inMemory(true)` and the default +`inMemory(false)` template mode are supported. + +Place list placeholders in the table's data rows. To preserve a totals row or content below +the list, enable row insertion: + +```java +FillConfig config = FillConfig.builder().forceNewRow(true).build(); +excelWriter.fill(data, config, writeSheet); +``` + +The table range includes its totals row; the AutoFilter range excludes it. Without row +insertion, a table can grow into unused rows, and a fill that would overwrite another table +or a totals row is rejected. Row insertion moves entire worksheet rows, so every table +intersected by that movement shifts or expands accordingly. Tables on other sheets and +tables outside the affected rows retain their ranges. An empty collection leaves tables unchanged. + +Table names, column metadata, styles, calculated-column definitions and totals definitions +are preserved. Structured-reference syntax is retained when ordinary A1 references in the +same formula move. Fesod preserves native calculated-column definitions and requests +recalculation when Excel opens the result; it does not evaluate those formulas or populate +every generated row's formula cache. + +This support covers row growth in tables with one header row and at most one totals row. +Horizontal expansion, inconsistent column metadata, overlapping tables, duplicate table +names and growth beyond worksheet limits are rejected. It does not create new native +tables or add native table support to XLS files. + +For sheet cloning through POI, clone a pristine template before filling, using +`inMemory(true)`. POI creates independent table parts and names; subsequent fills track the +clone separately. Cloning an already-filled runtime sheet and advanced formula remapping +are outside this behavior. + ## Simple Fill ### Overview diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md index d6f8458d79..9fb78fb7e2 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md @@ -41,6 +41,33 @@ title: '填充' 转义只是让大括号不被解析,而 `\` 本身只有在同一个单元格里还存在真实占位符时才会被去掉。如果单元格里没有别的内容,`\{name\}` 会原样写出,包括反斜杠。 +## Excel 原生表格 + +列表填充会识别 XLSX 模板中通过“插入 → 表格”创建的 Excel 原生表格,它与 Fesod 的 +`WriteTable` API 是两个概念。写入结束时,Fesod 根据最终行位置同步表格范围和 AutoFilter +范围,支持重复填充、插行引起的表格移动,以及两种 `inMemory` 模板模式。 + +列表占位符应位于表格的数据行。存在汇总行或需要保留列表下方内容时,启用插行: + +```java +FillConfig config = FillConfig.builder().forceNewRow(true).build(); +excelWriter.fill(data, config, writeSheet); +``` + +表格范围包含汇总行,AutoFilter 范围不包含汇总行。不开启插行时,表格可以向空闲行扩展; +会覆盖汇总行或其他表格的填充会报错。插行会移动整行,因此与这些行相交的其他表格也会相应 +移动或扩展。其他工作表、受影响行之外的表格保持范围不变;空列表保持表格不变。 + +表格名称、列元数据、样式、计算列定义和汇总定义会被保留。混合公式中的普通 A1 引用移动时, +结构化引用语法保持不变。Fesod 保留原生计算列定义,并要求 Excel 打开结果时重新计算; +它不会计算这些公式,也不会为每个新增行写入公式缓存值。 + +当前支持只有一个表头行、至多一个汇总行的表格按行扩展。横向扩列、列元数据不一致、表格 +重叠、名称重复或超过工作表行列上限时会报错。此功能不自动创建原生表格,也不扩展到 XLS。 + +通过 POI 克隆工作表时,请使用 `inMemory(true)`,在填充前克隆原始模板。POI 会创建独立的 +表格部件和名称,后续填充单独跟踪副本。克隆已填充的运行时工作表及复杂公式重映射不在此范围内。 + ## 简单填充 ### 概述