Como trabalhar com estilos

Artigo
01/21/2025

Este tópico aborda o SDK WorksheetOpen XML , Chartsheetas classes e DialogSheet como 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 de Folha de CálculoML, veja Estrutura de um documento de Folha de CálculoML.

Folhas na Folha de CálculoML

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

As folhas são as estruturas centrais dentro de um livro e são onde o utilizador faz a maior parte das respetivas folhas de cálculo. O tipo de folha mais comum é a folha de cálculo, que é representada como uma grelha de células. As células da folha de cálculo podem conter texto, números, datas e fórmulas. As células também podem ser formatadas. Normalmente, os livros contêm mais do que uma folha. Para ajudar na análise de dados e tomar decisões informadas, as aplicações de folha de cálculo implementam frequentemente funcionalidades e objetos que ajudam a calcular, ordenar, filtrar, organizar e apresentar informações graficamente. Uma vez que estas funcionalidades estão muitas vezes muito ligadas à grelha da folha de cálculo, estas também estão incluídas na definição da folha no disco.

Outros tipos de folhas incluem folhas de gráfico e folhas de caixa de diálogo.

Abrir a Classe de Folha de Cálculo do SDK XML

A classe Open XML SDK Worksheet representa o worksheet elemento (<worksheet/>) definido no esquema Open XML File Format para documentos de Folha de CálculoML. Utilize a Worksheet classe para manipular elementos individuais <worksheet/> num documento de Folha de CálculoML.

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

Uma instância deste tipo de peça contém todos os dados, fórmulas e características associadas a uma determinada folha de cálculo.

Um pacote deve conter exatamente uma parte da Folha de Cálculo por folha de cálculo

Especificamente, o atributo ID no elemento da folha deve fazer referência à parte da folha de cálculo pretendida.

O elemento raiz de uma parte deste tipo de conteúdo deve ser a folha de cálculo.

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

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

<worksheet>
    <sheetData/>
</worksheet>

A coleção empty sheetData representa uma grelha vazia; este elemento é obrigatório. Conforme definido no esquema, algumas coleções de propriedades de folha opcionais podem aparecer antes de sheetData e algumas podem aparecer depois. Para simplificar a lógica necessária para inserir uma nova folha Coleção de dados numa folha existente (mas vazia), a coleção sheetData é necessária, mesmo quando está vazia.

Uma folha de cálculo típica tem, pelo menos, uma folha de cálculo. A folha de cálculo contém uma tabela como a estrutura para definir dados, representada pelo sheetData elemento . Uma folha que contenha dados utiliza o worksheet elemento como elemento raiz para definir folhas de cálculo. Dentro de uma folha de cálculo, os dados são divididos em três secções distintas. A primeira secção contém propriedades opcionais da folha. A segunda secção contém os dados, utilizando o elemento necessário sheetData . A terceira secção contém funcionalidades de suporte opcionais, como proteção de folhas e informações de filtro. Para definir uma folha de cálculo vazia, só tem de utilizar os worksheet elementos e sheetData . O sheetData elemento pode estar vazio.

Para criar novos valores para a folha de cálculo, defina linhas dentro do sheetData elemento . Estas linhas contêm células, que contêm valores. O row elemento define uma nova linha. Normalmente, a primeira linha na sheetData é a primeira linha na folha visível. Dentro da linha que criar novo cells com o <c/> elemento . Os valores das células podem ser fornecidos ao armazenar um <v/> elemento dentro da célula. Normalmente, o <v/> elemento contém o valor atual da célula da folha de cálculo. Se o valor for um valor numérico, será armazenado diretamente no <v/> elemento no ficheiro XML. Se o valor for um valor de cadeia, é armazenado numa tabela de cadeia partilhada. Para obter mais informações sobre como utilizar a tabela de cadeias partilhadas para armazenar valores de cadeia, veja Trabalhar com a tabela de cadeia partilhada.

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

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

Para obter mais informações sobre elementos de folha de cálculo opcionais, como propriedades da folha e funcionalidades 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 de dados da folha (<sheetData/>).

A tabela de células é a estrutura principal de uma folha de cálculo. Consiste em todo o texto, números e fórmulas na grelha.

Classe de Linha

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

As células na tabela de células estão organizadas por linha. Cada linha tem um índice (atributo r) para que as linhas vazias não precisem de ser escritas. Cada linha indica o número de células definidas para a mesma, bem como a respetiva posição relativa na folha. 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 de célula (<c/>).

A própria célula é expressa pela coleção c. Cada célula indica a respetiva localização na grelha através da notação de referência de estilo A1. Uma célula também pode indicar um identificador de estilo (atributo s) e um tipo de dados (atributo t). Os tipos de célula incluem cadeia, número e Booleano. Para otimizar as operações de carregamento/gravação, os valores de dados predefinidos não são escritos.

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, se os valores foram introduzidos diretamente (por exemplo, a célula A2 no nosso exemplo tem o valor Ligação Externa:) ou se são o resultado de um cálculo (por exemplo, a célula B3 no nosso exemplo tem a fórmula B2+1).

Os valores de cadeia numa célula não são armazenados na tabela de células, a menos que sejam o resultado de um cálculo. Por conseguinte, em vez de ver a Ligação Externa como o conteúdo do nó v da célula, verá um índice baseado em zero na tabela de cadeia partilhada onde essa cadeia é armazenada exclusivamente. Isto é feito para otimizar o desempenho de carga/guardar e reduzir a duplicação de informações. Para determinar se o 0 em v é um número ou um índice para uma cadeia, o tipo de dados da célula tem de ser examinado. Quando o tipo de dados indica cadeia, é um índice e não um valor numérico.

Open XML SDK Code Example

O seguinte exemplo de código cria um documento de folha de cálculo com o nome de ficheiro 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

Folha de Cálculo GeradaML

Quando o código SDK Open XML é executado, o seguinte XML é escrito no documento Folha de CálculoML referenciado no código. Para ver este XML, abra o ficheiro "sheet.xml" na pasta "folhas de cálculo" do ficheiro .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>

Classe de Folha de Gráficos do SDK Open XML

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

Uma instância deste tipo de peça representa um gráfico armazenado na sua própria folha.

Um pacote tem permissão para conter zero ou mais peças de Folha de Gráficos.

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

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

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

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

Classe de Desenho

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

Uma instância deste tipo de peça contém as informações de apresentação e esquema para um ou mais elementos de desenho que estão presentes nesta folha de cálculo.

É permitido que um pacote contenha uma ou mais partes de Desenhos e cada uma dessas partes deve ser alvo de uma relação explícita de uma peça de folha de cálculo (\12.3.24) ou de uma parte da Folha de Gráficos (\12.3.2). Deve existir apenas uma parte desenhos por folha de cálculo ou folha de gráficos.

Open XML SDK Dialogsheet Class

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

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

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

O elemento raiz de uma parte deste tipo de conteúdo deve ser uma folha 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