Skip to content

Commit 17dfd66

Browse files
SasthaPrathapSasthaPrathap
authored
Merge pull request #1963 from syncfusion-content/996178-MergedCells
996178: Need to documentation for merged cell feature in spreadsheet
2 parents ccf1196 + 7bfbea2 commit 17dfd66

File tree

6 files changed

+163
-0
lines changed

6 files changed

+163
-0
lines changed

‎Document-Processing-toc.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5165,6 +5165,7 @@
51655165
<li><a href="/document-processing/excel/spreadsheet/blazor/open-and-save">Open and Save</a></li>
51665166
<li><a href="/document-processing/excel/spreadsheet/blazor/worksheet">Worksheet</a></li>
51675167
<li><a href="/document-processing/excel/spreadsheet/blazor/cell-range">Cell Range</a></li>
5168+
<li><a href="/document-processing/excel/spreadsheet/blazor/merge-cell">Merge Cells</a></li>
51685169
<li><a href="/document-processing/excel/spreadsheet/blazor/editing">Editing</a></li>
51695170
<li><a href="/document-processing/excel/spreadsheet/blazor/formulas">Formulas</a></li>
51705171
<li><a href="/document-processing/excel/spreadsheet/blazor/formatting">Formatting</a></li>

‎Document-Processing/Excel/Spreadsheet/Blazor/images/merge-cells.gif‎

300 KB
Loading

‎Document-Processing/Excel/Spreadsheet/Blazor/images/mergecell-dialog.png‎

99.8 KB
Loading

‎Document-Processing/Excel/Spreadsheet/Blazor/images/mergecell-same-size-cell.png‎

59.4 KB
Loading

‎Document-Processing/Excel/Spreadsheet/Blazor/images/unmerge-cells.gif‎

150 KB
Loading

‎Document-Processing/Excel/Spreadsheet/Blazor/merge-cell.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
layout: post
3+
title: Merge cells in Blazor Spreadsheet component | Syncfusion
4+
description: Checkout and learn all about the comprehensive merge functionality in Syncfusion Blazor Spreadsheet component and much more.
5+
platform: document-processing
6+
control: Spreadsheet
7+
documentation: ug
8+
---
9+
10+
# Merge cells in Blazor Spreadsheet component
11+
12+
Merging cells in the Blazor Spreadsheet component allows you to combine adjacent cells into a single larger cell, improving layout and readability. This feature is commonly used to create headers, section labels, or grouped content for a structured view. To control this functionality, use the [AllowMerge](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Spreadsheet.SfSpreadsheet.html#Syncfusion_Blazor_Spreadsheet_SfSpreadsheet_AllowMerge) property, which enables or disables merge cell support in the Spreadsheet. The default value of the `AllowMerge` property is true.
13+
14+
N> When `AllowMerge` is set to **`false`**, merge options are **disabled** in the Ribbon. API methods related to merging will also be inactive. Additionally, if the **worksheet is protected**, the merging feature is disabled. For more information, refer to the [Worksheet Protection](./protection#protect-sheet) documentation.
15+
16+
## Merge operations
17+
18+
The Blazor Spreadsheet supports the following merge operations:
19+
20+
| Operation | Description |
21+
| -- | -- |
22+
| Merge cells | Combines all selected cells into one single cell. The value from the top-left cell is kept. |
23+
| Merge & center | Combines all selected cells into one single cell and centers the content horizontally. The value from the top-left cell is kept. |
24+
| Merge across | Merges cells row by row across columns in the selection. Each row keeps its first cell value. |
25+
| Unmerge cells | Reverses a merge and restores individual cells. The top-left cell value remains, and other cells are cleared. |
26+
27+
N> The **Merge Cell** button is disabled when a single unmerged cell is selected. Merge options are also unavailable when the sheet is protected.
28+
29+
## Merge Cells
30+
31+
### Merge cells via UI
32+
33+
- Select a range of cells to merge.
34+
- Click on **Merge Cell** drop-down in the ribbon.
35+
- Choose one of the following option:
36+
- **Merge & Center**
37+
- **Merge Across**
38+
- **Merge Cells**
39+
40+
![merge cells](./images/merge-cells.gif)
41+
42+
When merging cells through the user interface, a validation dialog is displayed to inform that only the upper-left cell value will be retained and other values will be discarded.
43+
44+
![merge cell validation message](./images/mergecell-dialog.png)
45+
46+
N> Clicking the **Merge Cells** button (not the drop-down) applies the default action. If the selection is not merged, the cells are merged into a single cell. If the selection includes or intersects a merged range, that merged range is unmerged.
47+
48+
### Merge cells programmatically
49+
50+
The [MergeAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Spreadsheet.SfSpreadsheet.html#Syncfusion_Blazor_Spreadsheet_SfSpreadsheet_MergeAsync_System_String_System_String_) method merges cells based on the specified merge type. If the **cellRange** parameter is not provided, the current selection is used. This method provides a programmatic way to merge cells without using the UI. The available parameters in the `MergeAsync` method are:
51+
52+
| Parameter | Type | Description |
53+
| -- | -- | -- |
54+
| mergeType | **MergeType** | Specifies the merge behavior.<br><br> the Default MergeType is `MergeType.Cells`. Supported values:<br> - `Cells` - Merge the entire selection into one cell and preserve the top-left value;<br> - `Center` - Merge the entire selection and horizontally center the resulting cell’s content;<br> - `Across` - For each row in the selection, merge the cells across columns and preserve each row’s first cell value. |
55+
| cellRange | string (optional) | Specifies the A1-style address of the range to unmerge (e.g., `"A1:D1"`). If not provided, the currently selected range will be unmerged. |
56+
57+
{% tabs %}
58+
{% highlight razor tabtitle="Index.razor" %}
59+
60+
@using Syncfusion.Blazor.Spreadsheet
61+
62+
<button class="e-btn" @onclick="MergeSelection">Merge cells</button>
63+
<button class="e-btn" @onclick="MergeAcrossRange">Merge across</button>
64+
<button class="e-btn" @onclick="MergeAndCenterRange">Merge & center</button>
65+
66+
<SfSpreadsheet @ref="SpreadsheetInstance" DataSource="DataSourceBytes">
67+
<SpreadsheetRibbon></SpreadsheetRibbon>
68+
</SfSpreadsheet>
69+
70+
@code {
71+
public byte[] DataSourceBytes { get; set; }
72+
public SfSpreadsheet SpreadsheetInstance;
73+
74+
protected override void OnInitialized()
75+
{
76+
string filePath = "wwwroot/Sample.xlsx";
77+
DataSourceBytes = File.ReadAllBytes(filePath);
78+
}
79+
80+
private async Task MergeSelection()
81+
{
82+
// Merge the current selection into a single cell
83+
await SpreadsheetInstance.MergeAsync(MergeType.Cells);
84+
}
85+
86+
private async Task MergeAcrossRange()
87+
{
88+
// For each row in the range, merge across its columns
89+
await SpreadsheetInstance.MergeAsync(MergeType.Across, "C2:E6");
90+
}
91+
92+
private async Task MergeAndCenterRange()
93+
{
94+
// Merge the range and center-align the merged cell’s content
95+
await SpreadsheetInstance.MergeAsync(MergeType.Center, "A1:D1");
96+
}
97+
98+
}
99+
100+
{% endhighlight %}
101+
{% endtabs %}
102+
103+
## Unmerge Cells
104+
105+
### Unmerge cells via UI
106+
107+
- Select a range of cells to unmerge.
108+
- Click on **Merge Cell** drop-down in the ribbon.
109+
- Choose **Unmerge cells** option.
110+
111+
![unmerge cells](./images/unmerge-cells.gif)
112+
113+
### Unmerge cells programmatically.
114+
115+
The [UnmergeAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Spreadsheet.SfSpreadsheet.html#Syncfusion_Blazor_Spreadsheet_SfSpreadsheet_UnmergeAsync_System_String_System_String_) method reverses a merge and restores individual cells. If the **cellRange** parameter is not provided, the current selection cell is unmerged. This method provides a programmatic way to unmerge cells without using the UI. The available parameters in the `UnmergeAsync` method are:
116+
117+
| Parameter | Type | Description |
118+
| -- | -- | -- |
119+
| cellRange | string (optional) | Specifies the A1-style address of the range to unmerge (e.g., "A1:D1"). If not provided, the currently selected range will be unmerged. |
120+
121+
{% tabs %}
122+
{% highlight razor tabtitle="Index.razor" %}
123+
124+
@using Syncfusion.Blazor.Spreadsheet
125+
126+
<button class="e-btn" @onclick="UnmergeRange">Unmerge</button>
127+
128+
<SfSpreadsheet @ref="SpreadsheetInstance" DataSource="DataSourceBytes">
129+
<SpreadsheetRibbon></SpreadsheetRibbon>
130+
</SfSpreadsheet>
131+
132+
@code {
133+
public byte[] DataSourceBytes { get; set; }
134+
public SfSpreadsheet SpreadsheetInstance;
135+
136+
protected override void OnInitialized()
137+
{
138+
string filePath = "wwwroot/Sample.xlsx";
139+
DataSourceBytes = File.ReadAllBytes(filePath);
140+
}
141+
142+
private async Task UnmergeRange()
143+
{
144+
// Unmerge the specified merged region
145+
await SpreadsheetInstance.UnmergeAsync("A1:D1");
146+
}
147+
}
148+
149+
{% endhighlight %}
150+
{% endtabs %}
151+
152+
### Limitations of Merge
153+
154+
When merging cells in the Blazor Spreadsheet, certain constraints apply to ensure data integrity. In these cases, validation messages are displayed:
155+
156+
- **Sorting with merged cells** - When sorting a range that contains merged cells, a validation dialog appears to indicate that sorting cannot proceed unless all merged cells are consistent in size.
157+
158+
- **Autofill on merged cells** - When performing autofill and dropping the fill handle onto merged cells, a validation dialog appears to indicate that autofill requires all merged cells to be the same size.
159+
160+
These limitations are enforced to maintain data integrity and prevent unexpected behavior during operations like sorting and autofill.
161+
162+
![merge cell same cell size validation](./images/mergecell-same-size-cell.png)

0 commit comments

Comments
 (0)