Intercalar duas células adjacentes num documento de folha de cálculo

Este tópico mostra como utilizar as classes no SDK Open XML para o Office para intercalar duas células adjacentes num documento de folha de cálculo programaticamente.

---

Obtendo um Objeto SpreadsheetDocument

No SDK Open XML, a SpreadsheetDocument classe representa um pacote de documentos do Excel. Para abrir e trabalhar com um documento do Excel, crie uma instância da classe a SpreadsheetDocument partir do documento. Após criar a instância com base no documento, você pode obter acesso à parte da pasta de trabalho principal que contém as planilhas. O texto no documento é representado no pacote como XML com SpreadsheetML markup.

Para criar a instância de classe a partir do documento a que chama um dos Open métodos. São fornecidos vários, cada um deles com uma assinatura diferente. O código de exemplo deste tópico usa o método Open(String, Boolean) com uma assinatura que requer dois parâmetros. O primeiro parâmetro usa uma cadeia de caracteres de caminho completo que representa o documento que você deseja abrir. O segundo parâmetro é true ou false e representa se pretende que o ficheiro seja aberto para edição. Quaisquer alterações efetuadas ao documento não serão guardadas se este parâmetro for false.

---

Estrutura básica de um documento de folha de cálculoML

A estrutura de documentos básica de um SpreadsheetML documento consiste nos Sheets elementos e Sheet , que referenciam as folhas de cálculo no livro. Um arquivo XML separado é criado para cada planilha. Por exemplo, o SpreadsheetML para um Workbook que tem duas folhas de cálculo com o nome MySheet1 e MySheet2 está localizado no ficheiro Workbook.xml e é apresentado no seguinte exemplo de código.

    <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
    <workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
        <sheets>
            <sheet name="MySheet1" sheetId="1" r:id="rId1" /> 
            <sheet name="MySheet2" sheetId="2" r:id="rId2" /> 
        </sheets>
    </workbook>

Os ficheiros XML da folha de cálculo contêm um ou mais elementos de nível de bloco, como SheetData representa a tabela de células e contém um ou mais Row elementos. A row contém um ou mais Cell elementos. Cada célula contém um CellValue elemento que representa o valor da célula. Por exemplo, o para a SpreadsheetML primeira folha de cálculo num livro, que tem apenas o valor 100 na célula A1, está localizado no ficheiro Sheet1.xml e é apresentado no seguinte exemplo de código.

    <?xml version="1.0" encoding="UTF-8" ?> 
    <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
        <sheetData>
            <row r="1">
                <c r="A1">
                    <v>100</v> 
                </c>
            </row>
        </sheetData>
    </worksheet>

Com o SDK Open XML, pode criar a estrutura do documento e o conteúdo que utiliza classes com tipos fortes que correspondem a SpreadsheetML elementos. Pode encontrar estas classes no DocumentFormat.OpenXML.Spreadsheet espaço de nomes. A tabela seguinte lista os nomes das classes que correspondem aos workbookelementos , sheets, sheet, worksheete sheetData .

Elemento SpreadsheetML	Abrir Classe SDK XML	Descrição
<workbook/>	DocumentFormat.OpenXML.Spreadsheet.Workbook	O elemento raiz para a parte do documento principal.
<sheets/>	DocumentFormat.OpenXML.Spreadsheet.Sheets	O contêiner para as estruturas de nível de bloco, como sheet, fileVersion e outras indicadas na especificação ISO/IEC 29500.
<sheet/>	DocumentFormat.OpenXml.Spreadsheet.Sheet	Uma planilha que aponta para um arquivo de definição de planilha.
<worksheet/>	DocumentFormat.OpenXML.Spreadsheet. Planilha	Um arquivo de definição de planilha que contém os dados de planilha.
<sheetData/>	DocumentFormat.OpenXML.Spreadsheet.SheetData	A tabela de células, agrupadas por linhas.
<row/>	DocumentFormat.OpenXml.Spreadsheet.Row	Uma linha na tabela de células.
<c/>	DocumentFormat.OpenXml.Spreadsheet.Cell	Uma célula em uma linha.
<v/>	DocumentFormat.OpenXml.Spreadsheet.CellValue	O valor de uma célula.

---

Como funciona o código de exemplo

Depois de abrir o ficheiro de folha de cálculo para edição, o código verifica se as células especificadas existem e, se não existirem, cria-as ao chamar o CreateSpreadsheetCellIfNotExist método e acrescentá-las ao objeto adequado Row .

C#

// Given a Worksheet and a cell name, verifies that the specified cell exists.
// If it does not exist, creates a new cell. 
static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName)
{
    string columnName = GetColumnName(cellName);
    uint rowIndex = GetRowIndex(cellName);

    IEnumerable<Row> rows = worksheet.Descendants<Row>().Where(r => r.RowIndex?.Value == rowIndex);

    // If the Worksheet does not contain the specified row, create the specified row.
    // Create the specified cell in that row, and insert the row into the Worksheet.
    if (rows.Count() == 0)
    {
        Row row = new Row() { RowIndex = new UInt32Value(rowIndex) };
        Cell cell = new Cell() { CellReference = new StringValue(cellName) };
        row.Append(cell);
        worksheet.Descendants<SheetData>().First().Append(row);
    }
    else
    {
        Row row = rows.First();

        IEnumerable<Cell> cells = row.Elements<Cell>().Where(c => c.CellReference?.Value == cellName);

        // If the row does not contain the specified cell, create the specified cell.
        if (cells.Count() == 0)
        {
            Cell cell = new Cell() { CellReference = new StringValue(cellName) };
            row.Append(cell);
        }
    }
}

Visual Basic

' Given a Worksheet and a cell name, verifies that the specified cell exists.
' If it does not exist, creates a new cell. 
Sub CreateSpreadsheetCellIfNotExist(worksheet As Worksheet, cellName As String)
    Dim columnName As String = GetColumnName(cellName)
    Dim rowIndex As UInteger = GetRowIndex(cellName)

    Dim rows As IEnumerable(Of Row) = worksheet.Descendants(Of Row)().Where(Function(r) r.RowIndex?.Value = rowIndex)

    ' If the Worksheet does not contain the specified row, create the specified row.
    ' Create the specified cell in that row, and insert the row into the Worksheet.
    If rows.Count() = 0 Then
        Dim row As New Row() With {
            .RowIndex = New UInt32Value(rowIndex)
        }
        Dim cell As New Cell() With {
            .CellReference = New StringValue(cellName)
        }
        row.Append(cell)
        worksheet.Descendants(Of SheetData)().First().Append(row)
    Else
        Dim row As Row = rows.First()

        Dim cells As IEnumerable(Of Cell) = row.Elements(Of Cell)().Where(Function(c) c.CellReference?.Value = cellName)

        ' If the row does not contain the specified cell, create the specified cell.
        If cells.Count() = 0 Then
            Dim cell As New Cell() With {
                .CellReference = New StringValue(cellName)
            }
            row.Append(cell)
        End If
    End If
End Sub

Para obter um nome de coluna, o código cria uma nova expressão regular para corresponder à parte do nome da coluna do nome da célula. Esta expressão regular corresponde a qualquer combinação de letras maiúsculas ou minúsculas. Para obter mais informações sobre expressões regulares, veja Elementos de Linguagem de Expressão Regular. O código obtém o nome da coluna ao chamar Regex.Match.

C#

// Given a cell name, parses the specified cell to get the column name.
static string GetColumnName(string cellName)
{
    // Create a regular expression to match the column name portion of the cell name.
    Regex regex = new Regex("[A-Za-z]+");
    Match match = regex.Match(cellName);

    return match.Value;
}

Visual Basic

' Given a cell name, parses the specified cell to get the column name.
Function GetColumnName(cellName As String) As String
    ' Create a regular expression to match the column name portion of the cell name.
    Dim regex As New Regex("[A-Za-z]+")
    Dim match As Match = regex.Match(cellName)

    Return match.Value
End Function

Para obter o índice de linhas, o código cria uma nova expressão regular para corresponder à parte do índice de linhas do nome da célula. Esta expressão regular corresponde a qualquer combinação de dígitos decimais. O código seguinte cria uma expressão regular para corresponder à parte do índice de linhas do nome da célula, composta por dígitos decimais.

C#

// Given a cell name, parses the specified cell to get the row index.
static uint GetRowIndex(string cellName)
{
    // Create a regular expression to match the row index portion the cell name.
    Regex regex = new Regex(@"\d+");
    Match match = regex.Match(cellName);

    return uint.Parse(match.Value);
}

Visual Basic

' Given a cell name, parses the specified cell to get the row index.
Function GetRowIndex(cellName As String) As UInteger
    ' Create a regular expression to match the row index portion the cell name.
    Dim regex As New Regex("\d+")
    Dim match As Match = regex.Match(cellName)

    Return UInteger.Parse(match.Value)
End Function

Código de exemplo

O código seguinte intercala duas células adjacentes num pacote de Row documentos. Ao unir duas células, apenas o conteúdo de uma das células é preservado. Nos idiomas da esquerda para a direita, o conteúdo na célula superior esquerda é preservado. Nos idiomas da direita para a esquerda, o conteúdo na célula superior direita é preservado.

Este é o código de exemplo completo em C# e em Visual Basic.

C#

static void MergeTwoCells(string docName, string sheetName, string cell1Name, string cell2Name)
{
    // Open the document for editing.
    using (SpreadsheetDocument document = SpreadsheetDocument.Open(docName, true))
    {
        Worksheet? worksheet = GetWorksheet(document, sheetName);
        if (worksheet is null || string.IsNullOrEmpty(cell1Name) || string.IsNullOrEmpty(cell2Name))
        {
            return;
        }

        // Verify if the specified cells exist, and if they do not exist, create them.
        CreateSpreadsheetCellIfNotExist(worksheet, cell1Name);
        CreateSpreadsheetCellIfNotExist(worksheet, cell2Name);

        MergeCells mergeCells;
        if (worksheet.Elements<MergeCells>().Count() > 0)
        {
            mergeCells = worksheet.Elements<MergeCells>().First();
        }
        else
        {
            mergeCells = new MergeCells();

            // Insert a MergeCells object into the specified position.
            if (worksheet.Elements<CustomSheetView>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<CustomSheetView>().First());
            }
            else if (worksheet.Elements<DataConsolidate>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<DataConsolidate>().First());
            }
            else if (worksheet.Elements<SortState>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<SortState>().First());
            }
            else if (worksheet.Elements<AutoFilter>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<AutoFilter>().First());
            }
            else if (worksheet.Elements<Scenarios>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<Scenarios>().First());
            }
            else if (worksheet.Elements<ProtectedRanges>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<ProtectedRanges>().First());
            }
            else if (worksheet.Elements<SheetProtection>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<SheetProtection>().First());
            }
            else if (worksheet.Elements<SheetCalculationProperties>().Count() > 0)
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<SheetCalculationProperties>().First());
            }
            else
            {
                worksheet.InsertAfter(mergeCells, worksheet.Elements<SheetData>().First());
            }
        }

        // Create the merged cell and append it to the MergeCells collection.
        MergeCell mergeCell = new MergeCell() { Reference = new StringValue(cell1Name + ":" + cell2Name) };
        mergeCells.Append(mergeCell);
    }
}

// Given a Worksheet and a cell name, verifies that the specified cell exists.
// If it does not exist, creates a new cell. 
static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName)
{
    string columnName = GetColumnName(cellName);
    uint rowIndex = GetRowIndex(cellName);

    IEnumerable<Row> rows = worksheet.Descendants<Row>().Where(r => r.RowIndex?.Value == rowIndex);

    // If the Worksheet does not contain the specified row, create the specified row.
    // Create the specified cell in that row, and insert the row into the Worksheet.
    if (rows.Count() == 0)
    {
        Row row = new Row() { RowIndex = new UInt32Value(rowIndex) };
        Cell cell = new Cell() { CellReference = new StringValue(cellName) };
        row.Append(cell);
        worksheet.Descendants<SheetData>().First().Append(row);
    }
    else
    {
        Row row = rows.First();

        IEnumerable<Cell> cells = row.Elements<Cell>().Where(c => c.CellReference?.Value == cellName);

        // If the row does not contain the specified cell, create the specified cell.
        if (cells.Count() == 0)
        {
            Cell cell = new Cell() { CellReference = new StringValue(cellName) };
            row.Append(cell);
        }
    }
}

// Given a SpreadsheetDocument and a worksheet name, get the specified worksheet.
static Worksheet? GetWorksheet(SpreadsheetDocument document, string worksheetName)
{
    WorkbookPart workbookPart = document.WorkbookPart ?? document.AddWorkbookPart();
    IEnumerable<Sheet> sheets = workbookPart.Workbook.Descendants<Sheet>().Where(s => s.Name == worksheetName);

    string? id = sheets.First().Id;
    WorksheetPart? worksheetPart = id is not null ? (WorksheetPart)workbookPart.GetPartById(id) : null;

    return worksheetPart?.Worksheet;
}

// Given a cell name, parses the specified cell to get the column name.
static string GetColumnName(string cellName)
{
    // Create a regular expression to match the column name portion of the cell name.
    Regex regex = new Regex("[A-Za-z]+");
    Match match = regex.Match(cellName);

    return match.Value;
}

// Given a cell name, parses the specified cell to get the row index.
static uint GetRowIndex(string cellName)
{
    // Create a regular expression to match the row index portion the cell name.
    Regex regex = new Regex(@"\d+");
    Match match = regex.Match(cellName);

    return uint.Parse(match.Value);
}

Visual Basic

Sub MergeTwoCells(docName As String, sheetName As String, cell1Name As String, cell2Name As String)
    ' Open the document for editing.
    Using document As SpreadsheetDocument = SpreadsheetDocument.Open(docName, True)
        Dim worksheet As Worksheet = GetWorksheet(document, sheetName)
        If worksheet Is Nothing OrElse String.IsNullOrEmpty(cell1Name) OrElse String.IsNullOrEmpty(cell2Name) Then
            Return
        End If

        ' Verify if the specified cells exist, and if they do not exist, create them.
        CreateSpreadsheetCellIfNotExist(worksheet, cell1Name)
        CreateSpreadsheetCellIfNotExist(worksheet, cell2Name)

        Dim mergeCells As MergeCells
        If worksheet.Elements(Of MergeCells)().Count() > 0 Then
            mergeCells = worksheet.Elements(Of MergeCells)().First()
        Else
            mergeCells = New MergeCells()

            ' Insert a MergeCells object into the specified position.
            If worksheet.Elements(Of CustomSheetView)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of CustomSheetView)().First())
            ElseIf worksheet.Elements(Of DataConsolidate)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of DataConsolidate)().First())
            ElseIf worksheet.Elements(Of SortState)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SortState)().First())
            ElseIf worksheet.Elements(Of AutoFilter)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of AutoFilter)().First())
            ElseIf worksheet.Elements(Of Scenarios)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of Scenarios)().First())
            ElseIf worksheet.Elements(Of ProtectedRanges)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of ProtectedRanges)().First())
            ElseIf worksheet.Elements(Of SheetProtection)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetProtection)().First())
            ElseIf worksheet.Elements(Of SheetCalculationProperties)().Count() > 0 Then
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetCalculationProperties)().First())
            Else
                worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetData)().First())
            End If
        End If

        ' Create the merged cell and append it to the MergeCells collection.
        Dim mergeCell As New MergeCell() With {
            .Reference = New StringValue(cell1Name & ":" & cell2Name)
        }
        mergeCells.Append(mergeCell)
    End Using
End Sub

' Given a Worksheet and a cell name, verifies that the specified cell exists.
' If it does not exist, creates a new cell. 
Sub CreateSpreadsheetCellIfNotExist(worksheet As Worksheet, cellName As String)
    Dim columnName As String = GetColumnName(cellName)
    Dim rowIndex As UInteger = GetRowIndex(cellName)

    Dim rows As IEnumerable(Of Row) = worksheet.Descendants(Of Row)().Where(Function(r) r.RowIndex?.Value = rowIndex)

    ' If the Worksheet does not contain the specified row, create the specified row.
    ' Create the specified cell in that row, and insert the row into the Worksheet.
    If rows.Count() = 0 Then
        Dim row As New Row() With {
            .RowIndex = New UInt32Value(rowIndex)
        }
        Dim cell As New Cell() With {
            .CellReference = New StringValue(cellName)
        }
        row.Append(cell)
        worksheet.Descendants(Of SheetData)().First().Append(row)
    Else
        Dim row As Row = rows.First()

        Dim cells As IEnumerable(Of Cell) = row.Elements(Of Cell)().Where(Function(c) c.CellReference?.Value = cellName)

        ' If the row does not contain the specified cell, create the specified cell.
        If cells.Count() = 0 Then
            Dim cell As New Cell() With {
                .CellReference = New StringValue(cellName)
            }
            row.Append(cell)
        End If
    End If
End Sub

' Given a SpreadsheetDocument and a worksheet name, get the specified worksheet.
Function GetWorksheet(document As SpreadsheetDocument, worksheetName As String) As Worksheet
    Dim workbookPart As WorkbookPart = If(document.WorkbookPart, document.AddWorkbookPart())
    Dim sheets As IEnumerable(Of Sheet) = workbookPart.Workbook.Descendants(Of Sheet)().Where(Function(s) s.Name = worksheetName)

    Dim id As String = sheets.First().Id
    Dim worksheetPart As WorksheetPart = If(id IsNot Nothing, CType(workbookPart.GetPartById(id), WorksheetPart), Nothing)

    Return If(worksheetPart IsNot Nothing, worksheetPart.Worksheet, Nothing)
End Function

' Given a cell name, parses the specified cell to get the column name.
Function GetColumnName(cellName As String) As String
    ' Create a regular expression to match the column name portion of the cell name.
    Dim regex As New Regex("[A-Za-z]+")
    Dim match As Match = regex.Match(cellName)

    Return match.Value
End Function

' Given a cell name, parses the specified cell to get the row index.
Function GetRowIndex(cellName As String) As UInteger
    ' Create a regular expression to match the row index portion the cell name.
    Dim regex As New Regex("\d+")
    Dim match As Match = regex.Match(cellName)

    Return UInteger.Parse(match.Value)
End Function

---

Confira também

• Open XML SDK class library reference (Referência da biblioteca de classes SDK Open XML)