Como trabalhar com estilos

Artigo
11/16/2023

Este tópico discute as classes Open XML SDK Worksheet, Chartsheet e DialogSheet e como elas se relacionam com o esquema Open XML File Format SpreadsheetML. Para obter mais informações sobre a estrutura geral das partes e elementos que compõem um documento SpreadsheetML, consulte Estrutura de um documento SpreadsheetML.

Planilhas em PlanilhaML

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento planilha (<planilha>).

As planilhas são as estruturas centrais dentro de uma pasta de trabalho e são onde o usuário faz a maior parte do trabalho de planilha. O tipo mais comum de planilha é a planilha, que é representada como uma grade de células. As células de planilha podem conter texto, números, datas e fórmulas. As células também podem ser formatadas. As pastas de trabalho geralmente contêm mais de uma planilha. Para ajudar na análise de dados e na tomada de decisões informadas, os aplicativos de planilha geralmente implementam recursos e objetos que ajudam a calcular, classificar, filtrar, organizar e exibir informações graficamente. Como esses recursos geralmente são conectados muito fortemente com a grade de planilha, eles também são incluídos na definição de planilha em disco.

Outros tipos de planilhas incluem planilhas de gráficos e planilhas de diálogo.

Abrir classe de planilha do SDK do XML

A classe Open XML SDKWorksheet representa o elemento de planilha (<planilha>) definido no esquema Open XML File Format para documentos SpreadsheetML. Use a classe Planilha para manipular elementos de planilha> individuais < em um documento SpreadsheetML.

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento planilha (<planilha>).

Uma instância desse tipo de parte contém todos os dados, fórmulas e características associados a uma determinada planilha.

Um pacote deve conter exatamente uma parte de planilha por planilha

Especificamente, o atributo id no elemento de planilha deve fazer referência à parte da planilha desejada.

O elemento raiz de uma parte desse tipo de conteúdo deve ser a planilha.

As informações a seguir da especificação ISO/IEC 29500 introduzem o cenário mínimo da planilha.

A menor folha possível (em branco) é a seguinte:

<worksheet>
    <sheetData/>
</worksheet>

A coleção sheetData vazia representa uma grade vazia; esse elemento é necessário. Conforme definido no esquema, algumas coleções opcionais de propriedades de planilha podem ser exibidas antes de sheetData, e algumas podem aparecer depois. Para simplificar a lógica necessária para inserir uma nova coleção sheetData em uma planilha existente (mas vazia), a coleção sheetData é necessária, mesmo quando vazia.

Uma planilha típica tem pelo menos uma planilha. A planilha contém uma tabela como estrutura para definir dados, representada pelo elemento sheetData . Uma planilha que contém dados usa o elemento de planilha como o elemento raiz para definir planilhas. Dentro de uma planilha, os dados são divididos em três seções distintas. A primeira seção contém propriedades opcionais da planilha. A segunda seção contém os dados, usando o elemento sheetData necessário. A terceira seção contém recursos de suporte opcionais, como proteção de planilha e informações de filtro. Para definir uma planilha vazia, você só precisa usar a planilha e os elementos sheetData . O elemento sheetData pode estar vazio.

Para criar novos valores para a planilha, você define linhas dentro do elemento sheetData . Essas linhas contêm células, que contêm valores. O elemento de linha define uma nova linha. Normalmente, a primeira linha na planilhaData é a primeira linha na folha visível. Dentro da linha, você cria novas células usando o < elemento c>. Os valores para células podem ser fornecidos armazenando um < elemento v> dentro da célula. Normalmente, o < elemento v> contém o valor atual da célula de planilha. Se o valor for um valor numérico, ele será armazenado diretamente no < elemento v> no arquivo XML. Se o valor for um valor de cadeia de caracteres, ele será armazenado em uma tabela de cadeia de caracteres compartilhada. Para obter mais informações sobre como usar a tabela de cadeia de caracteres compartilhada para armazenar valores de cadeia de caracteres, consulte Trabalhar com a tabela de cadeia de caracteres compartilhada.

A tabela a seguir lista as classes comuns de SDK Open XML usadas ao trabalhar com a classe Worksheet .

Elemento SpreadsheetML	Classe SDK Open XML
sheetData	SheetData
row	Linha
c	Cell
v	CellValue

Para obter mais informações sobre elementos de planilha opcionais, como propriedades de planilha e recursos de planilha de suporte, consulte a especificação ISO/IEC 29500.

Classe SheetData

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento sheet data (<sheetData>).

A tabela de células é a estrutura principal de uma planilha. Ele consiste em todo o texto, números e fórmulas na grade.

Classe Row

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento linha (<linha>).

As células na tabela de células são organizadas por linha. Cada linha tem um índice (atributo r) para que linhas vazias não precisem ser gravadas. Cada linha indica o número de células definidas para ela, bem como sua posição relativa na planilha. Neste exemplo, a primeira linha de dados é a linha 2.

Classe Cell

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento célula (<c>).

A célula em si é expressa pela coleção c. Cada célula indica sua localização na grade usando a notação de referência no estilo A1. Uma célula também pode indicar um identificador de estilo (atributos s) e um tipo de dados (atributo t). Os tipos de célula incluem cadeia de caracteres, número e booliano. Para otimizar operações de carga/salvamento, os valores de dados padrão não são descartados.

Classe CellValue

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento valor de célula (<v>).

As células contêm valores, se os valores foram inseridos diretamente (por exemplo, a célula A2 em nosso exemplo tem o valor Link Externo:) ou são o resultado de um cálculo (por exemplo, a célula B3 em nosso exemplo tem a fórmula B2+1).

Os valores de cadeia de caracteres em uma célula não são armazenados na tabela de células, a menos que sejam o resultado de um cálculo. Portanto, em vez de ver Link Externo: como o conteúdo do nó v da célula, em vez disso, você verá um índice baseado em zero na tabela de cadeia de caracteres compartilhada em que essa cadeia de caracteres é armazenada exclusivamente. Isso é feito para otimizar o desempenho de carga/salvamento e reduzir a duplicação de informações. Para determinar se o 0 em v é um número ou um índice para uma cadeia de caracteres, o tipo de dados da célula deve ser examinado. Quando o tipo de dados indica cadeia de caracteres, ele é um índice e não um valor numérico.

Abrir o exemplo de código do SDK XML

O exemplo de código a seguir cria um documento de planilha com o nome do arquivo especificado e instancia uma classe de Planilha e adiciona uma linha e adiciona uma célula à tabela de células na posição A1. Em seguida, o valor da célula no A1 é definido como igual ao valor numérico 100.

C#
Visual Basic

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Spreadsheet;

CreateSpreadsheetWorkbook(args[0]);

static void CreateSpreadsheetWorkbook(string filepath)
{
    // Create a spreadsheet document by supplying the filepath.
    // By default, AutoSave = true, Editable = true, and Type = xlsx.
    SpreadsheetDocument spreadsheetDocument = SpreadsheetDocument.Create(filepath, SpreadsheetDocumentType.Workbook);

    // Add a WorkbookPart to the document.
    WorkbookPart workbookPart = spreadsheetDocument.AddWorkbookPart();
    workbookPart.Workbook = new Workbook();

    // Add a WorksheetPart to the WorkbookPart.
    WorksheetPart worksheetPart = workbookPart.AddNewPart<WorksheetPart>();
    worksheetPart.Worksheet = new Worksheet(new SheetData());

    // Add Sheets to the Workbook.
    Sheets sheets = workbookPart.Workbook.AppendChild<Sheets>(new Sheets());

    // Append a new worksheet and associate it with the workbook.
    Sheet sheet = new Sheet() { Id = workbookPart.GetIdOfPart(worksheetPart), SheetId = 1, Name = "mySheet" };
    sheets.Append(sheet);

    // Get the sheetData cell table.
    SheetData sheetData = worksheetPart.Worksheet.GetFirstChild<SheetData>() ?? worksheetPart.Worksheet.AppendChild(new SheetData());

    // Add a row to the cell table.
    Row row;
    row = new Row() { RowIndex = 1 };
    sheetData.Append(row);

    // In the new row, find the column location to insert a cell in A1.  
    Cell? refCell = null;

    foreach (Cell cell in row.Elements<Cell>())
    {
        if (string.Compare(cell.CellReference?.Value, "A1", true) > 0)
        {
            refCell = cell;
            break;
        }
    }

    // Add the cell to the cell table at A1.
    Cell newCell = new Cell() { CellReference = "A1" };
    row.InsertBefore(newCell, refCell);

    // Set the cell value to be a numeric value of 100.
    newCell.CellValue = new CellValue("100");
    newCell.DataType = new EnumValue<CellValues>(CellValues.Number);

    // Dispose the document.
    spreadsheetDocument.Dispose();
}

Imports DocumentFormat.OpenXml
Imports DocumentFormat.OpenXml.Packaging
Imports DocumentFormat.OpenXml.Spreadsheet

Module MyModule

    Sub Main(args As String())
    End Sub

    Public Sub CreateSpreadsheetWorkbookWithNumValue(ByVal filepath As String)
        ' Create a spreadsheet document by supplying the filepath.
        ' By default, AutoSave = true, Editable = true, and Type = xlsx.
        Dim spreadsheetDocument As SpreadsheetDocument = SpreadsheetDocument.Create(filepath, SpreadsheetDocumentType.Workbook)

        ' Add a WorkbookPart to the document.
        Dim workbookpart As WorkbookPart = spreadsheetDocument.AddWorkbookPart()
        workbookpart.Workbook = New Workbook()

        ' Add a WorksheetPart to the WorkbookPart.
        Dim worksheetPart As WorksheetPart = workbookpart.AddNewPart(Of WorksheetPart)()
        worksheetPart.Worksheet = New Worksheet(New SheetData())

        ' Add Sheets to the Workbook.
        Dim sheets As Sheets = spreadsheetDocument.WorkbookPart.Workbook.AppendChild(Of Sheets)(New Sheets())

        ' Append a new worksheet and associate it with the workbook.
        Dim sheet As New Sheet() With {.Id = spreadsheetDocument.WorkbookPart.GetIdOfPart(worksheetPart), .SheetId = 1, .Name = "mySheet"}
        sheets.Append(sheet)

        ' Get the sheetData cell table.
        Dim sheetData As SheetData = worksheetPart.Worksheet.GetFirstChild(Of SheetData)()

        ' Add a row to the cell table.
        Dim row As Row
        row = New Row() With {.RowIndex = 1}
        sheetData.Append(row)

        ' In the new row, find the column location to insert a cell in A1.  
        Dim refCell As Cell = Nothing
        For Each cell As Cell In row.Elements(Of Cell)()
            If String.Compare(cell.CellReference.Value, "A1", True) > 0 Then
                refCell = cell
                Exit For
            End If
        Next

        ' Add the cell to the cell table at A1.
        Dim newCell As New Cell() With {.CellReference = "A1"}
        row.InsertBefore(newCell, refCell)

        ' Set the cell value to be a numeric value of 100.
        newCell.CellValue = New CellValue("100")
        newCell.DataType = New EnumValue(Of CellValues)(CellValues.Number)

        ' Dispose the document.
        spreadsheetDocument.Dispose()
    End Sub
End Module

Planilha geradaML

Quando o código do SDK Open XML é executado, o XML a seguir é gravado no documento SpreadsheetML referenciado no código. Para exibir esse XML, abra o arquivo "sheet.xml" na pasta "planilhas" do arquivo .zip.

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

Classe Open XML SDK Chartsheet

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento chartsheet (<gráfico>).

Uma instância desse tipo de parte representa um gráfico armazenado em sua própria planilha.

Um pacote tem permissão para conter zero ou mais partes do Chartsheet.

Exemplo: sheet1.xml refere-se a um desenho que é o destino de uma relação no item de relação da parte chartsheet:

<chartsheet xmlns:r="…" …>
    <sheetViews>
        <sheetView scale="64"/>
    </sheetViews\>
    <drawing r:id="rId1">
</chartsheet>

A tabela a seguir lista as classes comuns de SDK Open XML usadas ao trabalhar com a classe Chartsheet .

Elemento SpreadsheetML	Classe SDK Open XML
Desenho	Desenho

Classe de desenho

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento desenho (<wsDr>).

Uma instância desse tipo de parte contém as informações de apresentação e layout de um ou mais elementos de desenho presentes nesta planilha.

Um pacote tem permissão para conter uma ou mais partes de Desenhos, e cada uma dessas partes deve ser o destino de uma relação explícita de uma parte de planilha (§12.3.24) ou uma parte de Planilha (§12.3.2). Deve haver apenas uma parte de Desenhos por planilha ou planilha.

Classe de planilha abrir SDK do XML

As informações a seguir da especificação ISO/IEC 29500 introduzem o elemento de planilha (<folha> de diálogo).

Uma instância desse tipo de parte contém informações sobre uma caixa de diálogo personalizada herdada para um formulário de usuário.

Um pacote tem permissão para conter uma ou mais partes da planilha de diálogo

O elemento raiz de uma parte desse tipo de conteúdo deve ser a planilha de diálogo.

Exemplo: sheet1.xml contém o seguinte:

<dialogsheet xmlns:r="…" …>
    <sheetPr>
        <pageSetUpPr/>
    </sheetPr>
    <sheetViews>
        …
    </sheetViews>
    …
    <legacyDrawing r:id="rId1"/>
</dialogsheet>

Compartilhar via