Trabalhando com Tabelas

Trabalhando com Tabelas

Tabelas em Aspose.Words FOSS para .NET são representadas pelo Aspose.Words.Tables espaço de nomes: Table, Row, e Cell formam uma hierarquia de nós compostos de três níveis que fica na árvore do documento ao lado de parágrafos. Esta página cobre a criação de tabelas com DocumentBuilder, formatando linhas e células, controlando o layout de toda a tabela e mesclando células.

O Modelo de Objeto de Tabela

Um Table é um CompositeNode que contém nós Row, e cada Row é um CompositeNode que contém nós Cell; um Cell por sua vez contém parágrafos e, potencialmente, tabelas aninhadas. Table.Rows retorna um RowCollection, Row.Cells retorna um CellCollection, e um Body ou outro Story expõe cada tabela de nível superior nele através da sua propriedade Tables, um TableCollection. Todas as três coleções suportam Add(), Insert(), Remove(), RemoveAt(), Contains() e IndexOf(). Table.EnsureMinimum(), Row.EnsureMinimum() e Cell.EnsureMinimum() preenchem, respectivamente, o menor conteúdo válido que um nó desse tipo necessita (uma linha vazia, uma célula vazia ou um parágrafo vazio) após edições programáticas deixarem-no sem ele.

Criando Tabelas com DocumentBuilder

DocumentBuilder.StartTable() inicia uma nova tabela no cursor, InsertCell() adiciona uma célula à linha atual, EndRow() fecha a linha atual e EndTable() encerra a tabela. Defina DocumentBuilder.CellFormat e DocumentBuilder.RowFormat antes de chamar InsertCell() ou EndRow() para aplicar a formatação padrão a células e linhas à medida que são criadas — essas propriedades funcionam como um modelo para o conteúdo que o construtor insere a seguir, não como uma alteração retroativa nas células já presentes no documento.

Formatação de Células e Linhas

Cell.CellFormat é uma instância CellFormat (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) com ClearFormatting() para redefini-la e SetPaddings() para definir todos os quatro preenchimentos de célula de uma só vez. Row.RowFormat é uma instância RowFormat (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) com seu próprio ClearFormatting().

Formatação de Tabela Inteira e AutoFit

Table em si expõe propriedades de layout – Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions), TextWrapping, e metadados de acessibilidade via Title e Description. Table.AutoFit(AutoFitBehavior) redimensiona a tabela e suas células de acordo com o comportamento fornecido. SetBorder() define um lado da borda e SetBorders() define todas as bordas com o mesmo estilo de linha, largura e cor em toda a tabela; ClearBorders() e ClearShading() redefinem esses. ConvertToHorizontallyMergedCells() converte células que foram mescladas por largura correspondente em células que são explicitamente marcadas com HorizontalMerge.

Larguras Preferidas e de Célula

PreferredWidth representa uma largura e sua unidade, criada com os métodos de fábrica estáticos PreferredWidth.FromPercent() ou PreferredWidth.FromPoints(); PreferredWidthType identifica que tipo de valor (Auto, Percent ou Points) um determinado PreferredWidth contém. Tanto Table.PreferredWidth quanto CellFormat.PreferredWidth aceitam esses valores.

Células Mescladas

CellFormat.HorizontalMerge e CellFormat.VerticalMerge (CellMerge) indicam como uma célula participa de uma mesclagem horizontal ou vertical com seus vizinhos. CellVerticalAlignment controla como o conteúdo é justificado dentro de uma célula verticalmente, independentemente de qualquer estado de mesclagem.

Dicas e Melhores Práticas

• Feche cada StartTable() com um EndRow() correspondente por linha e um EndTable() final – uma linha ou tabela não fechada deixa o estado interno do construtor (e a árvore de documentos resultante) malformada.
• Defina DocumentBuilder.CellFormat e DocumentBuilder.RowFormat antes de cada chamada de InsertCell() ou EndRow() se linhas ou células diferentes na mesma tabela precisarem de formatação distinta; o construtor aplica o que estiver definido no momento da inserção.
• Chame Table.EnsureMinimum(), Row.EnsureMinimum() ou Cell.EnsureMinimum() após remover conteúdo programaticamente para que o nó mantenha a estrutura mínima válida que o Word espera.
• Use PreferredWidth.FromPercent() para tabelas que devem se adaptar à largura de página disponível, e PreferredWidth.FromPoints() para uma largura de layout fixa.
• AutoFitBehavior é aplicado quando você chama Table.AutoFit() – ele não é executado continuamente à medida que você adiciona ou remove conteúdo, portanto chame-o novamente após edições significativas se precisar que a tabela seja reajustada.

Problemas comuns

FAQ

Como eu construo uma tabela do zero com DocumentBuilder?

Chame StartTable(), então InsertCell() para cada célula em uma linha, EndRow() para fechar a linha, repita para linhas adicionais e, finalmente, EndTable() para fechar a tabela.

Como definir uma largura de tabela baseada em porcentagem em vez de uma largura fixa?

Atribua Table.PreferredWidth = PreferredWidth.FromPercent(value) em vez de PreferredWidth.FromPoints(value).

Como redefinir toda a formatação em uma célula ou linha?

Chame CellFormat.ClearFormatting() no CellFormat de uma célula, ou RowFormat.ClearFormatting() no RowFormat de uma linha.

Como definir bordas e sombreamento para toda a tabela de uma só vez?

Use Table.SetBorders() para uma borda uniforme em todos os lados, Table.SetBorder() para um lado de cada vez, e Table.SetShading() para sombreamento uniforme; ClearBorders() e ClearShading() redefinem-nas.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation