Como Trabalhar com Tabelas em .NET
Este guia mostra como criar, formatar e ler tabelas programaticamente em Aspose.Words FOSS para .NET, usando o Table, Row, e Cell classes no Aspose.Words.Tables namespace junto com DocumentBuilder. Ele cobre a construção de uma tabela do zero, formatação de células e linhas enquanto você constrói, controle do layout da tabela inteira e AutoFit, definição de larguras preferenciais, mesclagem de células e leitura de tabelas já presentes em um documento carregado.
Guia Passo a Passo
Etapa 1: Instalar o Pacote
Aspose.Words FOSS para .NET ainda não publica um pacote NuGet – construa a biblioteca a partir do código-fonte. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, então compile Aspose.Words.sln na configuração Release com o SDK .NET e referencie o assembly Aspose.Words resultante no seu projeto. A biblioteca tem como alvo o .NET Standard 2.0, portanto funciona no .NET Framework 4.6.2+ e .NET 6/8/10.
Etapa 2: Importar Classes Necessárias
Adicione uma diretiva using Aspose.Words; para as classes de documento principais (Document, DocumentBuilder) e uma diretiva using Aspose.Words.Tables; para as classes específicas de tabela que este guia cobre — Table, Row, Cell, CellFormat, RowFormat, PreferredWidth e enums relacionados.
Etapa 3: Crie uma nova tabela com DocumentBuilder
Crie um Document e um DocumentBuilder vinculados a ele, então chame DocumentBuilder.StartTable() para iniciar uma tabela no cursor. Para cada célula em uma linha, chame DocumentBuilder.InsertCell(), então feche a linha com DocumentBuilder.EndRow(). Repita para quantas linhas a tabela precisar, e feche a tabela inteira com DocumentBuilder.EndTable(). Cada StartTable() precisa de um EndTable() correspondente, e cada linha precisa de um EndRow() correspondente, senão o estado interno do construtor — e a árvore de documento resultante — ficam malformados.
Etapa 4: Formate células e linhas enquanto as cria
Defina DocumentBuilder.CellFormat e DocumentBuilder.RowFormat antes de chamar InsertCell() ou EndRow() para aplicar formatação às células e linhas que o construtor está prestes a criar — essas duas propriedades funcionam como um modelo para novo conteúdo, não como uma alteração retroativa nas células já inseridas. CellFormat expõe Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, e as quatro propriedades de preenchimento (LeftPadding, RightPadding, TopPadding, BottomPadding), que podem ser definidas todas de uma vez com SetPaddings(). RowFormat expõe Borders, Height, HeightRule, AllowBreakAcrossPages e HeadingFormat. Chame CellFormat.ClearFormatting() ou RowFormat.ClearFormatting() para redefinir qualquer um deles para os padrões antes de definir novos valores para a próxima linha ou célula.
Etapa 5: Defina o layout da tabela inteira e AutoFit
Depois que a tabela existir, defina as propriedades de layout diretamente no objeto Table: Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions) e TextWrapping. Chame Table.SetBorders() para aplicar um estilo de borda, largura e cor em toda a tabela, ou Table.SetBorder() para definir um único lado; ClearBorders() e ClearShading() redefinem esses valores. Table.AutoFit(AutoFitBehavior) redimensiona a tabela e suas células de acordo com o comportamento escolhido — chame-a novamente após qualquer edição estrutural, pois ela reflete o estado da tabela apenas no momento em que é executada, não continuamente.
Etapa 6: Defina larguras preferidas e de células
Crie valores de largura com os métodos de fábrica estáticos PreferredWidth.FromPercent() para um layout que se adapta à largura de página disponível, ou PreferredWidth.FromPoints() para uma largura fixa; PreferredWidthType informa que tipo de valor (Auto, Percent ou Points) um determinado PreferredWidth possui. Atribua o resultado a Table.PreferredWidth para a tabela inteira ou a CellFormat.PreferredWidth para uma única célula.
Etapa 7: Mesclar Células
Marque as células como mescladas definindo CellFormat.HorizontalMerge ou CellFormat.VerticalMerge (ambos digitados CellMerge) nas células que devem participar da mesclagem. Se as células foram apenas feitas para parecer mescladas ao combinar suas larguras em vez de serem explicitamente sinalizadas, chame Table.ConvertToHorizontallyMergedCells() para converter essa disposição visual em células com estado real de CellMerge. CellVerticalAlignment controla como o conteúdo é justificado verticalmente dentro de uma célula, independentemente de qualquer mesclagem.
Etapa 8: Ler Tabelas de um Documento Existente
Para trabalhar com tabelas já presentes em um documento carregado, leia Body.Tables (ou a propriedade Tables em qualquer outro Story) — um TableCollection — em vez de criar novos. Table.Rows retorna um RowCollection e Row.Cells retorna um CellCollection; os três tipos de coleções suportam Add(), Insert(), Remove(), RemoveAt(), Contains() e IndexOf() para edições programáticas. Após remover linhas ou células, chame Table.EnsureMinimum(), Row.EnsureMinimum() ou Cell.EnsureMinimum() para que o nó mantenha a estrutura mínima válida que o Word espera — uma linha vazia, uma célula vazia ou um parágrafo vazio, respectivamente.
Problemas Comuns e Soluções
Um documento salvo parece malformado, ou ocorre um erro ao salvar Uma linha ou a própria tabela nunca foi fechada. Sempre emparelhe DocumentBuilder.StartTable() com um final EndTable(), e feche cada linha com EndRow() antes de passar para a próxima ou encerrar a tabela.
Novas células não herdam a formatação que eu defini CellFormat and RowFormat foram alteradas no DocumentBuilder depois que as células afetadas já foram inseridas. Defina DocumentBuilder.CellFormat / RowFormat antes do InsertCell() or EndRow() chamada que cria o conteúdo que você deseja formatar.
A tabela não redimensiona da maneira que eu espero após eu editar seu conteúdo Table.AutoFit(AutoFitBehavior) reflete a estrutura da tabela apenas no momento em que é chamada. Chame-a novamente após qualquer edição estrutural — adicionando ou removendo linhas, células ou conteúdo — se o layout precisar ser reajustado.
Células que parecem mescladas comportam-se como células separadas ao serem lidas novamente As células foram correspondidas apenas pela largura, não foram marcadas com CellMerge. Chame Table.ConvertToHorizontallyMergedCells(), ou defina CellFormat.HorizontalMerge / VerticalMerge explicitamente nas células que devem ser mescladas.
Remover linhas ou células deixa a tabela em um estado inválido O Word espera que cada Table, Row, e Cell para manter uma estrutura mínima válida. Após remover o conteúdo programaticamente, chame EnsureMinimum() no nó recém-modificado.
Perguntas Frequentes
Como eu construo uma tabela do zero em vez de editar uma já existente?
Use DocumentBuilder: chame StartTable(), depois InsertCell() para cada célula em uma linha, EndRow() para fechar a linha, repita para linhas adicionais, e EndTable() para fechar a tabela.
Como obtenho as tabelas que já existem em um documento carregado?
Leia a propriedade Tables (um TableCollection) no Body da seção de interesse, ou em qualquer outro Story, como um cabeçalho ou rodapé.
Como faço para definir uma tabela como uma porcentagem da largura da página em vez de uma largura fixa?
Atribua Table.PreferredWidth = PreferredWidth.FromPercent(value) em vez de PreferredWidth.FromPoints(value).
Qual é a diferença entre definir bordas com SetBorders e SetBorder?
Table.SetBorders() aplica um estilo de linha, largura e cor a todas as bordas da tabela de uma vez; Table.SetBorder() define um único lado, permitindo que diferentes lados tenham formatações distintas.
Como redefinir a formatação em uma célula ou linha antes de reutilizá-la?
Chame CellFormat.ClearFormatting() no CellFormat da célula, ou RowFormat.ClearFormatting() no RowFormat da linha.
