Auto Merge Cells | Document Solutions for Excel, Java Edition

Auto Merge Cells

In This Topic

DsExcel allows you to add auto-merge information for a range that needs the merging of neighboring cells containing identical text using autoMerge method of IWorksheet interface. autoMerge method initiates an automatic merging operation that only takes effect at the moment of exporting the workbook to PDF, HTML, Image, .xlsx, .sjs, or Json with setIncludeAutoMergedCells method of XlsxSaveOptions, SjsSaveOptions, SerializationOptions, PdfSaveOptions, ImageSaveOptions, and HtmlSaveOptions classes set to true.

autoMerge method has the following parameters that help in adding and customizing the auto-merge operation:

Parameter Name	Description
range	The range for the auto-merge.
direction	The direction for the auto-merge. The default value is Column. AutoMergeDirection provides the following auto-merge directions: Row: Applies the auto-merge in row direction. Column: Applies the auto-merge in column direction. ColumnRow: Applies the auto-merge in column direction, preferentially, then in row direction. RowColumn: Applies the auto-merge in row direction, preferentially, then in column direction. None: Cancels the auto-merge.
mode	The mode for the auto-merge. The default value is Free. AutoMergeMode provides the following auto-merge modes: Free: Applies the auto-merge when neighboring cells have the same value. Restricted: Applies the auto-merge when neighboring cells have the same value and the corresponding cells in the previous row or column are merged automatically.
selectionMode	The selection mode for the auto-merge. The default value is Source. AutoMergeSelectionMode provides the following auto-merge selection modes: Source: Selects individual cell when the auto-merge is applied. This will take effect only when setIncludeAutoMergedCells is false. Merged: Selects all cells that have the same value when the auto-merge is applied. Note: selectionMode parameter is only applicable to SpreadJS.

Refer to the following example code to add auto-merge information for a range and export the workbook as .xlsx, .sjs, .pdf, and .png files:

Java	Copy Code
// Create a new workbook. var workbook = new Workbook(); // Open existing workbook. workbook.open("Regional_Product_List.xlsx"); // Get active worksheet. var worksheet = workbook.getActiveSheet(); // Add auto-merge range with restricted mode and merged selection mode. worksheet.autoMerge(worksheet.getUsedRange(), AutoMergeDirection.Column, AutoMergeMode.Restricted, AutoMergeSelectionMode.Merged); // Set IncludeAutoMergedCells to true to include the automatically merged cells. // Set XlsxSaveOptions to export workbook as XLSX file. XlsxSaveOptions xlsxOptions = new XlsxSaveOptions(); xlsxOptions.setIncludeAutoMergedCells(true); // Set SjsSaveOptions to export workbook as .sjs file. SjsSaveOptions sjsOptions = new SjsSaveOptions(); sjsOptions.setIncludeAutoMergedCells(true); // Set PdfSaveOptions to export workbook as PDF file. PdfSaveOptions pdfOptions = new PdfSaveOptions(); pdfOptions.setIncludeAutoMergedCells(true); // Set ImageSaveOptions to export workbook as PNG file. ImageSaveOptions pngOptions = new ImageSaveOptions(); pngOptions.setIncludeAutoMergedCells(true); // Save workbook as XLSX file. workbook.save("AutoMerge.xlsx", xlsxOptions); // Save workbook as .sjs file. workbook.save("AutoMerge.sjs", sjsOptions); // Save workbook as PDF file. workbook.save("AutoMerge.pdf", pdfOptions); // Save workbook as PNG file. worksheet.toImage("AutoMerge.png", pngOptions);

Java

Copy Code

// Create a new workbook.
var workbook = new Workbook();

// Open existing workbook.
workbook.open("Regional_Product_List.xlsx");

// Get active worksheet.
var worksheet = workbook.getActiveSheet();

// Add auto-merge range with restricted mode and merged selection mode.
worksheet.autoMerge(worksheet.getUsedRange(), AutoMergeDirection.Column, AutoMergeMode.Restricted, AutoMergeSelectionMode.Merged);

// Set IncludeAutoMergedCells to true to include the automatically merged cells.
// Set XlsxSaveOptions to export workbook as XLSX file.
XlsxSaveOptions xlsxOptions = new XlsxSaveOptions();
xlsxOptions.setIncludeAutoMergedCells(true);
        
// Set SjsSaveOptions to export workbook as .sjs file.
SjsSaveOptions sjsOptions = new SjsSaveOptions();
sjsOptions.setIncludeAutoMergedCells(true);

// Set PdfSaveOptions to export workbook as PDF file.
PdfSaveOptions pdfOptions = new PdfSaveOptions();
pdfOptions.setIncludeAutoMergedCells(true);

// Set ImageSaveOptions to export workbook as PNG file.
ImageSaveOptions pngOptions = new ImageSaveOptions();
pngOptions.setIncludeAutoMergedCells(true);

// Save workbook as XLSX file.
workbook.save("AutoMerge.xlsx", xlsxOptions);

// Save workbook as .sjs file.
workbook.save("AutoMerge.sjs", sjsOptions);

// Save workbook as PDF file.
workbook.save("AutoMerge.pdf", pdfOptions);

// Save workbook as PNG file.
worksheet.toImage("AutoMerge.png", pngOptions);

Without Auto Merge	With Auto Merge

Note:

The auto-merge operation will throw an exception if the ranges intersect with each other. For example, “A1:C3, B2:D4”.
The auto-merge operation will throw an exception if the range intersects an existing auto-merge range.
The auto-merge information is added for each area if the range has multiple areas. For example, “A1:B2, D3:E4.“
Inserting or deleting rows or columns will affect the auto-merge range. Any other API operations will not affect the auto-merge range.
The auto-merge operation will not change the workbook, so getMergeCells and getMergeArea methods of IRange interface cannot obtain the results of the auto-merge operation.
The auto-merged cells will be stored as normal span ranges in .xlsx, .sjs, and .json files if setIncludeAutoMergedCells is true.