Come Lavorare con le Tabelle in .NET
Questa guida mostra come creare, formattare e leggere tabelle programmaticamente in Aspose.Words FOSS per .NET, usando il Table, Row, e Cell classi nel Aspose.Words.Tables namespace insieme a DocumentBuilder. Copre la costruzione di una tabella da zero, la formattazione di celle e righe durante la creazione, il controllo del layout dell’intera tabella e AutoFit, l’impostazione delle larghezze preferite, l’unione di celle e la lettura di tabelle già presenti in un documento caricato.
Guida passo-passo
Passo 1: Installa il pacchetto
Aspose.Words FOSS per .NET non pubblica ancora un pacchetto NuGet — costruisci la libreria dal sorgente invece. Clona https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, poi compila Aspose.Words.sln in configurazione Release con l’SDK .NET e fai riferimento all’assembly Aspose.Words risultante dal tuo progetto. La libreria è destinata a .NET Standard 2.0, quindi funziona su .NET Framework 4.6.2+ e .NET 6/8/10.
Passo 2: Importa le classi richieste
Aggiungi una direttiva using Aspose.Words; per le classi di documento core (Document, DocumentBuilder) e una direttiva using Aspose.Words.Tables; per le classi specifiche per le tabelle coperte da questa guida — Table, Row, Cell, CellFormat, RowFormat, PreferredWidth e gli enum correlati.
Passo 3: Crea una nuova tabella con DocumentBuilder
Crea un Document e un DocumentBuilder collegato ad esso, quindi chiama DocumentBuilder.StartTable() per avviare una tabella al cursore. Per ogni cella in una riga, chiama DocumentBuilder.InsertCell(), quindi chiudi la riga con DocumentBuilder.EndRow(). Ripeti per quante righe necessita la tabella e chiudi l’intera tabella con DocumentBuilder.EndTable(). Ogni StartTable() richiede un EndTable() corrispondente, e ogni riga richiede un EndRow() corrispondente, altrimenti lo stato interno del builder — e l’albero del documento risultante — risulterà malformato.
Passo 4: Formatta celle e righe mentre le crei
Imposta DocumentBuilder.CellFormat e DocumentBuilder.RowFormat prima di chiamare InsertCell() o EndRow() per applicare la formattazione alle celle e alle righe che il builder sta per creare — queste due proprietà fungono da modello per i nuovi contenuti, non da modifica retroattiva alle celle già inserite. CellFormat espone Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth e le quattro proprietà di padding (LeftPadding, RightPadding, TopPadding, BottomPadding), che possono essere impostate tutte insieme con SetPaddings(). RowFormat espone Borders, Height, HeightRule, AllowBreakAcrossPages e HeadingFormat. Chiama CellFormat.ClearFormatting() o RowFormat.ClearFormatting() per ripristinare ciascuna ai valori predefiniti prima di impostare nuovi valori per la riga o la cella successiva.
Passo 5: Imposta il layout dell’intera tabella e AutoFit
Una volta che la tabella esiste, imposta le proprietà di layout direttamente sull’oggetto Table: Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions) e TextWrapping. Chiama Table.SetBorders() per applicare uno stile, larghezza e colore del bordo su tutta la tabella, oppure Table.SetBorder() per impostare un singolo lato; ClearBorders() e ClearShading() ripristinano questi. Table.AutoFit(AutoFitBehavior) ridimensiona la tabella e le sue celle secondo il comportamento scelto — richiamalo di nuovo dopo qualsiasi modifica strutturale, poiché riflette lo stato della tabella solo al momento dell’esecuzione, non in modo continuo.
Passo 6: Imposta le larghezze preferite e delle celle
Crea valori di larghezza con i metodi statici di fabbrica PreferredWidth.FromPercent() per un layout che si adatta alla larghezza della pagina disponibile, oppure PreferredWidth.FromPoints() per una larghezza fissa; PreferredWidthType indica quale tipo di valore (Auto, Percent o Points) possiede un determinato PreferredWidth. Assegna il risultato a Table.PreferredWidth per l’intera tabella o a CellFormat.PreferredWidth per una singola cella.
Passo 7: Unire le celle
Contrassegna le celle come unite impostando CellFormat.HorizontalMerge o CellFormat.VerticalMerge (entrambi digitati CellMerge) sulle celle che devono partecipare all’unione. Se le celle sono state fatte apparire unite solo abbinando le loro larghezze anziché essere esplicitamente contrassegnate, chiama Table.ConvertToHorizontallyMergedCells() per convertire quella disposizione visiva in celle con vero stato CellMerge. CellVerticalAlignment controlla come il contenuto è giustificato verticalmente all’interno di una cella, indipendentemente da qualsiasi unione.
Passo 8: Leggere le tabelle da un documento esistente
Per lavorare con le tabelle già presenti in un documento caricato, leggi Body.Tables (o la proprietà Tables su qualsiasi altro Story) — un TableCollection — anziché crearne di nuove. Table.Rows restituisce un RowCollection e Row.Cells restituisce un CellCollection; tutti e tre i tipi di collezione supportano Add(), Insert(), Remove(), RemoveAt(), Contains() e IndexOf() per modifiche programmatiche. Dopo aver rimosso righe o celle, chiama Table.EnsureMinimum(), Row.EnsureMinimum() o Cell.EnsureMinimum() affinché il nodo mantenga la struttura minima valida che Word si aspetta — una riga vuota, una cella vuota o un paragrafo vuoto, rispettivamente.
Problemi comuni e soluzioni
Un documento salvato appare malformato, o si verifica un errore durante il salvataggio Una riga o la tabella stessa non è mai stata chiusa. Assicurati sempre di abbinare DocumentBuilder.StartTable() con un finale EndTable(), e chiudi ogni riga con EndRow() prima di passare alla successiva o terminare la tabella.
Le nuove celle non ereditano la formattazione che ho impostato CellFormat and RowFormat sono state modificate il DocumentBuilder dopo che le celle interessate erano già state inserite. Imposta DocumentBuilder.CellFormat / RowFormat prima del InsertCell() or EndRow() chiamata che crea il contenuto che desideri formattare.
La tabella non si ridimensiona come mi aspetto dopo aver modificato il suo contenuto. Table.AutoFit(AutoFitBehavior) riflette la struttura della tabella solo al momento in cui viene chiamata. Richiamala di nuovo dopo qualsiasi modifica strutturale — aggiunta o rimozione di righe, celle o contenuti — se il layout deve essere riadattato.
Le celle che sembrano unite si comportano come celle separate quando vengono rilevate nuovamente. Le celle sono state abbinate solo per larghezza, non segnalate con. CellMerge. Call Table.ConvertToHorizontallyMergedCells(), or set CellFormat.HorizontalMerge / VerticalMerge esplicitamente sulle celle che dovrebbero unirsi.
Rimuovere righe o celle lascia la tabella in uno stato non valido Word si aspetta che ogni Table, Row, e Cell per mantenere una struttura minima valida. Dopo aver rimosso il contenuto programmaticamente, chiamare EnsureMinimum() sul nodo appena modificato.
Domande frequenti
Come creo una tabella da zero invece di modificare una esistente?
Usa DocumentBuilder: chiama StartTable(), poi InsertCell() per ogni cella in una riga, EndRow() per chiudere la riga, ripeti per righe aggiuntive, e EndTable() per chiudere la tabella.
Come ottengo le tabelle già presenti in un documento caricato?
Leggi la proprietà Tables (un TableCollection) sul Body della sezione di tuo interesse, o su qualsiasi altro Story come un’intestazione o un piè di pagina.
Come posso impostare una tabella su una percentuale della larghezza della pagina invece di una larghezza fissa?
Assegna Table.PreferredWidth = PreferredWidth.FromPercent(value) anziché PreferredWidth.FromPoints(value).
Qual è la differenza tra impostare i bordi con SetBorders e SetBorder?
Table.SetBorders() applica uno stile di linea, larghezza e colore a tutti i bordi della tabella contemporaneamente; Table.SetBorder() imposta un singolo lato, consentendo a lati diversi di avere formattazioni differenti.
Come faccio a ripristinare la formattazione su una cella o su una riga prima di riutilizzarla?
Chiama CellFormat.ClearFormatting() sul CellFormat della cella, o RowFormat.ClearFormatting() sul RowFormat della riga.
