Como trabalhar com estilos

Este tópico discute o Open XML SDK Worksheet Chartsheet, e DialogSheet as classes e como elas se relacionam com o esquema SpreadsheetML do formato de arquivo Open XML. 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 no SpreadsheetML

As seguintes informações da especificação ISO/IEC 29500 introduzem o elemento folha (<sheet/>).

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 da 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 auxiliar na análise de dados e na tomada de decisões informadas, os aplicativos de planilhas geralmente implementam recursos e objetos que ajudam a calcular, classificar, filtrar, organizar e exibir informações graficamente. Como esses recursos geralmente estão conectados muito fortemente à grade da planilha, eles também são incluídos na definição da planilha no disco.

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

Classe de planilha do Open XML SDK

A classe Open XML SDK Worksheet representa o worksheet elemento (<worksheet/>) definido no esquema Open XML File Format para documentos SpreadsheetML. Use a Worksheet classe para manipular elementos individuais <worksheet/> em um documento SpreadsheetML.

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

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

Um pacote deve conter exatamente uma parte da planilha por planilha

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

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

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

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

<worksheet>
    <sheetData/>
</worksheet>

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

Uma planilha típica tem pelo menos uma planilha. A planilha contém uma estrutura semelhante a uma tabela para definir os dados, representada pelo sheetData elemento. Uma planilha que contém dados usa o worksheet elemento 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 necessário sheetData . A terceira seção contém recursos de suporte opcionais, como proteção de chapas e informações de filtro. Para definir uma planilha vazia, você só precisa usar os worksheet elementos and sheetData . O sheetData elemento pode estar vazio.

Para criar novos valores para a planilha, defina linhas dentro do sheetData elemento. Essas linhas contêm células, que contêm valores. O row elemento define uma nova linha. Normalmente, a primeira linha do sheetData é a primeira linha da planilha visível. Dentro da linha, você cria um novo cells usando o <c/> elemento. Os valores das células podem ser fornecidos armazenando um <v/> elemento dentro da célula. Normalmente, o <v/> elemento contém o valor atual da célula da planilha. Se o valor for numérico, ele será armazenado diretamente no <v/> elemento no arquivo XML. Se o valor for uma 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 cadeias de caracteres compartilhada para armazenar valores de cadeias de caracteres, consulte Trabalhar com a tabela de cadeia de caracteres compartilhada.

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

Elemento SpreadsheetML	Classe Open XML SDK
`<sheetData/>`	SheetData
`<row/>`	Row
`<c/>`	Cell
`<v/>`	CellValue

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

Classe SheetData

As seguintes informações da especificação ISO/IEC 29500 introduzem o elemento dados da folha (<sheetData/>).

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

Classe de Linha

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

As células na tabela de células são organizadas por linhas. Cada linha tem um índice (atributo r) para que as 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 de célula

As seguintes informações da especificação ISO/IEC 29500 introduzem o elemento cell (<c/>).

A célula em si é expressa pela coleção c. Cada célula indica sua localização na grade usando 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 booleano. Para otimizar as operações de carregamento/salvamento, os valores de dados padrão não são gravados.

Classe CellValue

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

As células contêm valores, quer os valores tenham sido 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 o Link Externo como o conteúdo do nó v da célula, você vê 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 carregamento/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, é um índice e não um valor numérico.

Exemplo de código do Open XML SDK

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

C#
Visual Basic

static void CreateSpreadsheetWorkbook(string filepath)
{
    // Use 'using' block to ensure proper disposal of the document
    using (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(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 = 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);
    }
}

Sub CreateSpreadsheetWorkbook(filepath As String)
    ' Use 'Using' block to ensure proper disposal of the document
    Using 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 = workbookPart.Workbook.AppendChild(Of Sheets)(New Sheets())

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

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

        ' Add a row to the cell table.
        Dim row As 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 Cell = 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)
    End Using
End Sub

SpreadsheetML gerado

Quando o código do Open XML SDK é 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="http://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>

A classe Chartsheet do Open XML SDK

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

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

Um pacote pode conter zero ou mais partes de Chartsheet.

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

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

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

Elemento SpreadsheetML	Classe Open XML SDK
`<drawing/>`	Drawing

Aula de Desenho

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

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

Um pacote pode conter uma ou mais partes de Desenhos, e cada uma dessas partes deve ser o alvo de um relacionamento explícito de uma parte de Planilha (§12.3.24) ou uma parte de Folha de Gráfico (§12.3.2). Deve haver apenas uma parte de desenhos por planilha ou folha de gráfico.

Open XML SDK Dialogsheet Class

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

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

Um pacote pode conter uma ou mais partes de Dialogsheet

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

Exemplo: sheet1.xml contém o seguinte:

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

Last updated on 2026-08-21