feat: introduce header merge strategy for Excel writing (#674)

* feat: introduce header merge strategy for Excel writing

* feat: enhance header merge strategy with context validation and improved documentation

* feat: enhance header merge strategy with context validation and improved documentation

* feat: introduce HeaderMergeStrategy for flexible header merging and fix issue #666

* feat: introduce HeaderMergeStrategy for flexible header merging and fix issue #666

* Update fesod/src/test/java/org/apache/fesod/excel/head/HeaderMergeStrategyTest.java

Co-authored-by: Copilot <[email protected]>

* Update fesod/src/test/java/org/apache/fesod/excel/head/HeaderMergeStrategyTest.java

Co-authored-by: Copilot <[email protected]>

* feat: simplify canMergeVertically method by removing unused parameter

* doc: add line breaks for better readability in parameter documentation

---------

Co-authored-by: DeleiGuo <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Shuxin Pan <[email protected]>
Co-authored-by: gdliu3 <[email protected]>

Author: 5 people

fesod/src/main/java/org/apache/fesod/sheet/context/WriteContextImpl.java

@@ -25,6 +25,7 @@
 import java.util.Map;
 import java.util.UUID;
 import lombok.extern.slf4j.Slf4j;
+import org.apache.fesod.sheet.enums.HeaderMergeStrategy;
 import org.apache.fesod.sheet.enums.WriteTypeEnum;
 import org.apache.fesod.sheet.exception.ExcelGenerateException;
 import org.apache.fesod.sheet.metadata.CellRange;
@@ -296,8 +297,9 @@ public void initHead(ExcelWriteHeadProperty excelWriteHeadProperty) {
         }
         int newRowIndex = writeSheetHolder.getNewRowIndexAndStartDoWrite();
         newRowIndex += currentWriteHolder.relativeHeadRowIndex();
-        if (currentWriteHolder.automaticMergeHead()) {
-            addMergedRegionToCurrentSheet(excelWriteHeadProperty, newRowIndex);
+        HeaderMergeStrategy mergeStrategy = currentWriteHolder.headerMergeStrategy();
+        if (mergeStrategy != null && mergeStrategy != HeaderMergeStrategy.NONE) {
+            addMergedRegionToCurrentSheet(excelWriteHeadProperty, newRowIndex, mergeStrategy);
         }
         for (int relativeRowIndex = 0, i = newRowIndex;
                 i < excelWriteHeadProperty.getHeadRowNumber() + newRowIndex;
@@ -321,9 +323,11 @@ public void initHead(ExcelWriteHeadProperty excelWriteHeadProperty) {
      *
      * @param excelWriteHeadProperty The header property for writing.
      * @param rowIndex               The starting row index for merging.
+     * @param mergeStrategy         The merge strategy to use.
      */
-    private void addMergedRegionToCurrentSheet(ExcelWriteHeadProperty excelWriteHeadProperty, int rowIndex) {
-        for (CellRange cellRangeModel : excelWriteHeadProperty.headCellRangeList()) {
+    private void addMergedRegionToCurrentSheet(
+            ExcelWriteHeadProperty excelWriteHeadProperty, int rowIndex, HeaderMergeStrategy mergeStrategy) {
+        for (CellRange cellRangeModel : excelWriteHeadProperty.headCellRangeList(mergeStrategy)) {
             writeSheetHolder
                     .getSheet()
                     .addMergedRegionUnsafe(new CellRangeAddress(

fesod/src/main/java/org/apache/fesod/sheet/enums/HeaderMergeStrategy.java

@@ -0,0 +1,58 @@
+/*
+ * 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.enums;
+
+/**
+ * Header merge strategy for Excel writing.
+ * <p>
+ * When {@code headerMergeStrategy} is not set (null), the behavior is determined by
+ * {@code automaticMergeHead} for backward compatibility:
+ * {@code automaticMergeHead == true} → {@code AUTO}, {@code automaticMergeHead == false} → {@code NONE}.
+ * </p>
+ *
+ * @see org.apache.fesod.excel.write.metadata.WriteBasicParameter#getHeaderMergeStrategy()
+ * @see org.apache.fesod.excel.write.builder.AbstractExcelWriterParameterBuilder#headerMergeStrategy(HeaderMergeStrategy)
+ */
+public enum HeaderMergeStrategy {
+    /**
+     * No automatic merge
+     */
+    NONE,
+
+    /**
+     * Only horizontal merge (same cells in the same row)
+     */
+    HORIZONTAL_ONLY,
+
+    /**
+     * Only vertical merge (same cells in the same column).
+     */
+    VERTICAL_ONLY,
+
+    /**
+     * Only full rectangle merge (all cells must form a complete rectangle with the same name)
+     */
+    FULL_RECTANGLE,
+
+    /**
+     * Auto merge (default behavior for backward compatibility).
+     */
+    AUTO
+}

fesod/src/main/java/org/apache/fesod/sheet/write/builder/AbstractExcelWriterParameterBuilder.java

@@ -21,6 +21,7 @@
 
 import java.util.ArrayList;
 import java.util.Collection;
+import org.apache.fesod.sheet.enums.HeaderMergeStrategy;
 import org.apache.fesod.sheet.metadata.AbstractParameterBuilder;
 import org.apache.fesod.sheet.write.handler.WriteHandler;
 import org.apache.fesod.sheet.write.metadata.WriteBasicParameter;
@@ -88,6 +89,18 @@ public T automaticMergeHead(Boolean automaticMergeHead) {
         return self();
     }
 
+    /**
+     * Set header merge strategy.
+     * If not set, the behavior is determined by {@link #automaticMergeHead} for backward compatibility.
+     *
+     * @param strategy Header merge strategy
+     * @return this
+     */
+    public T headerMergeStrategy(HeaderMergeStrategy strategy) {
+        parameter().setHeaderMergeStrategy(strategy);
+        return self();
+    }
+
     /**
      * Ignore the custom columns.
      */

fesod/src/main/java/org/apache/fesod/sheet/write/metadata/WriteBasicParameter.java

@@ -25,6 +25,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
+import org.apache.fesod.sheet.enums.HeaderMergeStrategy;
 import org.apache.fesod.sheet.metadata.BasicParameter;
 import org.apache.fesod.sheet.write.handler.WriteHandler;
 
@@ -57,6 +58,11 @@ public class WriteBasicParameter extends BasicParameter {
      * Whether to automatically merge headers.Default is true.
      */
     private Boolean automaticMergeHead;
+    /**
+     * Header merge strategy.
+     * If null, the behavior is determined by {@link #automaticMergeHead} for backward compatibility.
+     */
+    private HeaderMergeStrategy headerMergeStrategy;
     /**
      * Ignore the custom columns.
      */

fesod/src/main/java/org/apache/fesod/sheet/write/metadata/holder/AbstractWriteHolder.java

@@ -37,6 +37,7 @@
 import org.apache.fesod.sheet.converters.ConverterKeyBuild;
 import org.apache.fesod.sheet.converters.DefaultConverterLoader;
 import org.apache.fesod.sheet.enums.HeadKindEnum;
+import org.apache.fesod.sheet.enums.HeaderMergeStrategy;
 import org.apache.fesod.sheet.event.NotRepeatExecutor;
 import org.apache.fesod.sheet.metadata.AbstractHolder;
 import org.apache.fesod.sheet.metadata.Head;
@@ -92,6 +93,11 @@ public abstract class AbstractWriteHolder extends AbstractHolder implements Writ
      * Whether to automatically merge headers.Default is true.
      */
     private Boolean automaticMergeHead;
+    /**
+     * Header merge strategy.
+     * If null, the behavior is determined by {@link #automaticMergeHead} for backward compatibility.
+     */
+    private HeaderMergeStrategy headerMergeStrategy;
 
     /**
      * Ignore the custom columns.
@@ -201,6 +207,17 @@ public AbstractWriteHolder(WriteBasicParameter writeBasicParameter, AbstractWrit
             this.automaticMergeHead = writeBasicParameter.getAutomaticMergeHead();
         }
 
+        if (writeBasicParameter.getHeaderMergeStrategy() == null) {
+            if (parentAbstractWriteHolder == null) {
+                // Backward compatibility: if headerMergeStrategy is not set, use automaticMergeHead
+                this.headerMergeStrategy = null;
+            } else {
+                this.headerMergeStrategy = parentAbstractWriteHolder.getHeaderMergeStrategy();
+            }
+        } else {
+            this.headerMergeStrategy = writeBasicParameter.getHeaderMergeStrategy();
+        }
+
         if (writeBasicParameter.getExcludeColumnFieldNames() == null && parentAbstractWriteHolder != null) {
             this.excludeColumnFieldNames = parentAbstractWriteHolder.getExcludeColumnFieldNames();
         } else {
@@ -517,6 +534,15 @@ public boolean automaticMergeHead() {
         return getAutomaticMergeHead();
     }
 
+    @Override
+    public HeaderMergeStrategy headerMergeStrategy() {
+        // Backward compatibility: if headerMergeStrategy is null, determine based on automaticMergeHead
+        if (headerMergeStrategy == null) {
+            return automaticMergeHead ? HeaderMergeStrategy.AUTO : HeaderMergeStrategy.NONE;
+        }
+        return headerMergeStrategy;
+    }
+
     @Override
     public boolean orderByIncludeColumn() {
         return getOrderByIncludeColumn();

fesod/src/main/java/org/apache/fesod/sheet/write/metadata/holder/WriteHolder.java

@@ -20,6 +20,7 @@
 package org.apache.fesod.sheet.write.metadata.holder;
 
 import java.util.Collection;
+import org.apache.fesod.sheet.enums.HeaderMergeStrategy;
 import org.apache.fesod.sheet.metadata.ConfigurationHolder;
 import org.apache.fesod.sheet.write.property.ExcelWriteHeadProperty;
 
@@ -59,6 +60,14 @@ public interface WriteHolder extends ConfigurationHolder {
      */
     boolean automaticMergeHead();
 
+    /**
+     * Get header merge strategy.
+     * If null, the behavior is determined by {@link #automaticMergeHead()} for backward compatibility.
+     *
+     * @return Header merge strategy
+     */
+    HeaderMergeStrategy headerMergeStrategy();
+
     /**
      * Writes the head relative to the existing contents of the sheet. Indexes are zero-based.
      *