Lavorare con il sommario
Spesso lavorerai con documenti contenenti un sommario (TOC). Utilizzando Aspose.Words puoi inserire il tuo sommario o ricostruire completamente il sommario esistente nel documento utilizzando solo poche righe di codice. Questo articolo descrive come utilizzare il campo del sommario e dimostra:
- Come inserire un nuovissimo
TOC - Aggiorna i sommari nuovi o esistenti nel documento.
- Specificare gli interruttori per controllare la formattazione e la struttura generale del sommario.
- Come modificare gli stili e l’aspetto del sommario.
- Come rimuovere un intero campo
TOCinsieme a tutte le voci dal documento.
Inserisci un sommario a livello di codice
È possibile inserire un campo TOC (sommario) nel documento nella posizione corrente chiamando il metodo DocumentBuilder.insert_table_of_contents.
Un sommario in un documento di Word può essere creato in diversi modi e formattato utilizzando una varietà di opzioni. Il campo passa al metodo per controllare il modo in cui la tabella viene creata e visualizzata nel documento.
Le opzioni predefinite utilizzate in un TOC inserito in Microsoft Word sono "\o “1-3 \h \z \u”. Le descrizioni di queste opzioni e un elenco di opzioni supportate sono disponibili più avanti nell’articolo. Puoi utilizzare quella guida per ottenere le opzioni corrette oppure, se hai già un documento contenente il TOC simile che desideri, puoi mostrare i codici di campo (ALT+F9) e copiare le opzioni direttamente dal campo.
L’esempio di codice seguente mostra come inserire un campo Sommario in un documento:
Il codice dimostra che il nuovo sommario viene inserito in un documento vuoto. La classe DocumentBuilder viene quindi utilizzata per inserire alcuni esempi di formattazione del contenuto con gli stili di intestazione appropriati utilizzati per contrassegnare il contenuto da includere nel sommario. Le righe successive popolano poi il TOC aggiornando i campi e il layout di pagina del documento.
TOC, ma senza contenuto visibile. Questo perché il campo TOC è stato inserito ma non è ancora popolato finché non viene aggiornato nel documento. Ulteriori informazioni a riguardo sono discusse nella sezione successiva.
Aggiorna il sommario
Aspose.Words ti consente di aggiornare completamente un TOC con solo poche righe di codice. Questo può essere fatto per popolare un TOC appena inserito o per aggiornare un TOC esistente dopo che sono state apportate modifiche al documento. Per aggiornare i campi TOC nel documento è necessario utilizzare i due metodi seguenti:
Tieni presente che questi due metodi di aggiornamento devono essere richiamati in quest’ordine. Se invertito, il sommario verrà popolato ma non verranno visualizzati i numeri di pagina. È possibile aggiornare un numero qualsiasi di TOC diversi. Questi metodi aggiorneranno automaticamente tutti i sommari trovati nel documento.
Il seguente esempio di codice mostra come ricostruire completamente i campi TOC nel documento richiamando l’aggiornamento del campo:
La prima chiamata a Document.update_fields creerà il TOC, tutte le voci di testo verranno popolate e il TOC apparirà quasi completo. Mancano solo i numeri di pagina che per ora vengono visualizzati con “?”. La seconda chiamata a Document.update_page_layout costruirà il layout del documento in memoria. Questo deve essere fatto per raccogliere i numeri di pagina delle voci. I numeri di pagina corretti calcolati da questa chiamata vengono quindi inseriti nel sommario.
Utilizza gli interruttori per controllare il comportamento del sommario.
Come con qualsiasi altro campo, il campo TOC può accettare opzioni definite all’interno del codice di campo che controllano il modo in cui viene creato il sommario. Alcuni interruttori vengono utilizzati per controllare quali voci includere e a quale livello, mentre altri vengono utilizzati per controllare l’aspetto del sommario. Gli interruttori possono essere combinati insieme per consentire la produzione di sommari complessi.
Per impostazione predefinita, queste opzioni sopra sono incluse quando si inserisce un TOC predefinito nel documento. Un TOC senza opzioni includerà il contenuto degli stili di intestazione incorporati (come se l’opzione \O fosse impostata). Gli switch TOC disponibili supportati da Aspose.Words sono elencati di seguito e i loro usi sono descritti in dettaglio. Possono essere divisi in sezioni separate in base alla loro tipologia. Gli interruttori nella prima sezione definiscono quale contenuto includere nel TOC e gli interruttori nella seconda sezione controllano l’aspetto del sommario. Se un’opzione non è elencata qui significa che al momento non è supportata. Tutti gli switch saranno supportati nelle versioni future. Stiamo aggiungendo ulteriore supporto con ogni versione.
Interruttori di contrassegno di ingresso
| Interruttore | Descrizione |
|---|---|
| Heading Styles (\Commutatore O) |
Questa opzione definisce che il |
Qualsiasi contenuto formattato con questi stili viene incluso nel sommario. Il livello dell'intestazione definirà il corrispondente livello gerarchico della voce nel TOC. Ad esempio, un paragrafo con stile Titolo 1 verrà trattato come il primo livello nel `TOC` mentre un paragrafo con Titolo 2 verrà trattato come il livello successivo nella gerarchia e così via.
| | **Outline Levels***(commutazione \U)* |
Ogni paragrafo può definire un livello di struttura in Opzioni paragrafo.
Questa impostazione determina a quale livello questo paragrafo deve essere trattato nella gerarchia del documento. Questa è una pratica comunemente utilizzata per strutturare facilmente il layout di un documento. Questa gerarchia può essere visualizzata passando alla visualizzazione struttura in Microsoft Word. Analogamente agli stili di intestazione, possono esserci da 1 a 9 livelli di struttura oltre al livello "Corpo del testo". I livelli di struttura da 1 a 9 verranno visualizzati nell'`TOC` nel livello corrispondente della gerarchia
Qualsiasi contenuto con un livello di struttura impostato nello stile di paragrafo o direttamente nel paragrafo stesso è incluso nel sommario. In Aspose.Words il livello della struttura è rappresentato dalla proprietà `ParagraphFormat.OutlineLevel` del nodo Paragrafo. Il livello di struttura di uno stile di paragrafo è rappresentato allo stesso modo dalla proprietà `Style.ParagraphFormat`.
Tieni presente che gli stili di titolo incorporati come Titolo 1 hanno un livello di struttura impostato obbligatoriamente nelle impostazioni di stile.
*(commutazione \T)* |
Questa opzione consentirà l'utilizzo di stili personalizzati durante la raccolta delle voci da utilizzare nel sommario. Viene spesso utilizzato insieme all'opzione \O per includere stili personalizzati insieme agli stili di intestazione incorporati nel sommario.
I parametri dell'interruttore devono essere racchiusi tra segni vocali. È possibile includere molti stili personalizzati, per ogni stile deve essere specificato il nome seguito da una virgola seguita dal livello con cui lo stile dovrebbe apparire nel `TOC`. Anche altri stili sono separati da una virgola.
Ad esempio
{ TOC \o "1-3" \t "CustomHeading1, 1, CustomHeading2, 2"}
utilizzerà il contenuto con stile CustomHeading1 come contenuto di livello 1 nel `TOC` e CustomHeading2 come livello 2.
| | **Use TC Fields***(Commutatori \F e \L)* |
Nelle versioni precedenti di Microsoft Word, l'unico modo per creare un `TOC` era l'uso dei campi TC. Questi campi vengono inseriti nascosti nel documento anche quando vengono visualizzati i codici di campo. Includono il testo che dovrebbe essere visualizzato nella voce e da essi viene creato il `TOC`. Questa funzionalità ora non viene utilizzata molto spesso ma può comunque essere utile in alcune occasioni per includere voci nel `TOC` che non sono rientrate per essere visibili nel documento.
Una volta inseriti, questi campi appaiono nascosti anche quando vengono visualizzati i codici di campo. Non possono essere visti senza mostrare contenuti nascosti. Per visualizzare questi campi è necessario selezionare Mostra formattazione paragrafo.
Questi campi possono essere inseriti in un documento in qualsiasi posizione come qualsiasi altro campo e sono rappresentati dall'enumerazione `FieldType.FieldTOCEntry`.L'opzione \F in un `TOC` viene utilizzata per specificare che i campi TC devono essere utilizzati come voci. Lo switch da solo senza alcun identificatore aggiuntivo significa che verrà incluso qualsiasi campo TC nel documento. Qualsiasi parametro aggiuntivo, spesso una singola lettera, indicherà che solo i campi TC che hanno un'opzione \f corrispondente verranno inclusi nel sommario. Ad esempio *
{ TOC \f t }
includerà solo i campi TC come
{ TC \f t }
Il campo `TOC` ha anche un interruttore correlato, l'interruttore "\L" specifica che sono inclusi solo i campi TC con livelli compresi nell'intervallo specificato.
Anche i campi `TC` stessi possono avere diversi interruttori impostati. Questi sono:
- *\F – Spiegato sopra.*
- *\L – Definisce in quale livello del `TOC` apparirà questo campo TC. Un `TOC` che utilizza questo stesso interruttore includerà questo campo TC solo se rientra nell'intervallo specificato.*
- `_\N` – La numerazione delle pagine per questa voce `TOC` non viene visualizzata. Un codice di esempio su come inserire i campi TC è disponibile nella sezione successiva.
|Interruttori relativi all’aspetto
| Interruttore | Descrizione |
|---|---|
| Omit Page Numbers (Commutazione \N) |
Questo interruttore viene utilizzato per nascondere i numeri di pagina per determinati livelli del sommario. Ad esempio puoi definire |
{TOC \o "1-4" \n "3-4" }
e i numeri di pagina sulle voci dei livelli 3 e quattro verranno nascosti insieme ai punti iniziali (se ce ne sono). Per specificare un solo livello è comunque necessario utilizzare un intervallo, ad esempio "1-1" escluderà i numeri di pagina solo per il primo livello.
Se non si fornisce alcun intervallo di livelli, verranno omessi i numeri di pagina per tutti i livelli nel sommario. È utile impostarlo quando si esporta un documento in HTML o formato simile. Questo perché i formati basati su HTML non hanno alcun concetto di pagina e quindi non necessitano di alcuna numerazione delle pagine.
| | **Insert As Hyperlinks***(\Commutatore H)* |
Questa opzione specifica che le voci `TOC` vengono inserite come collegamenti ipertestuali. Quando si visualizza un documento in Microsoft Word, queste voci appariranno comunque come testo normale all'interno del `TOC` ma sono collegate tramite collegamento ipertestuale e quindi possono essere utilizzate per spostarsi nella posizione della voce originale nel documento utilizzando *Ctrl + clic sinistro* in Microsoft Word. Quando questa opzione è inclusa, questi collegamenti vengono conservati anche in altri formati. Ad esempio, nei formati basati su HTML, incluso EPUB, e nei formati renderizzati come PDF e XPS, questi verranno esportati come collegamenti funzionanti.
Senza questo interruttore impostato, il `TOC` in tutti questi output verrà esportato come testo normale e non dimostrerà questo comportamento. Se un documento viene aperto in MS Word, anche il testo delle voci non sarà cliccabile in questo modo, ma i numeri di pagina potranno comunque essere utilizzati per navigare fino alla voce originale.
| | **Set Separator Character***(Commutazione \P)* |
Questo interruttore consente di modificare facilmente il contenuto che separa il titolo della voce e la numerazione delle pagine nel sommario. Il separatore da utilizzare deve essere specificato dopo questa opzione e racchiuso tra segni vocali.
Contrariamente a quanto documentato nella documentazione di Office, è possibile utilizzare un solo carattere invece di un massimo di cinque. Questo vale sia per MS Word che per Aspose.Words.
L'utilizzo di questa opzione non è consigliabile in quanto non consente un grande controllo su ciò che viene utilizzato per separare le voci e i numeri di pagina nel sommario. Si consiglia invece di modificare lo stile `TOC` appropriato come `StyleIdentifier.TOC1` e da lì modificare lo stile leader con accesso a membri di caratteri specifici, ecc. Ulteriori dettagli su come eseguire questa operazione sono disponibili più avanti nell'articolo.
| | **Preserve Tab Entries***(\Commutatore W)* |
L'utilizzo di questa opzione specificherà che tutte le voci che hanno un carattere di tabulazione, ad esempio un'intestazione che ha una tabulazione alla fine della riga, verranno conservate come carattere di tabulazione corretto durante la compilazione del sommario. Ciò significa che la funzione del carattere di tabulazione sarà presente nel `TOC` e potrà essere utilizzata per formattare la voce. Ad esempio, alcune voci possono utilizzare punti di tabulazione e caratteri di tabulazione per spaziare uniformemente il testo. Finché il livello `TOC` corrispondente definisce le tabulazioni equivalenti, le voci `TOC` generate appariranno con una spaziatura simile.
Nella stessa situazione, se questa opzione non fosse definita, i caratteri di tabulazione verrebbero convertiti in spazi bianchi equivalenti come tabulazioni non funzionanti. L'output quindi non apparirebbe come previsto.
| | **Preserve New Line Entries***(\Commutatore X)* |
Similmente all'opzione precedente, questa opzione specifica che le intestazioni che si estendono su più righe (utilizzando caratteri di nuova riga e non paragrafi separati) verranno conservate così come sono nel sommario generato. Ad esempio, un'intestazione che deve essere distribuita su più righe può utilizzare il carattere di nuova riga (Ctrl + Invio o `ControlChar.LineBreak`) per separare il contenuto su righe diverse. Con questa opzione specificata, la voce nel `TOC` conserverà questi caratteri di nuova riga come mostrato di seguito.
In questa situazione, se l'opzione non è definita, i caratteri di nuova riga vengono convertiti in un singolo spazio bianco.
|Inserisci campi TC
È possibile inserire un nuovo campo TC nella posizione corrente del DocumentBuilder chiamando il metodo DocumentBuilder.insert_field e specificando il nome del campo come “TC” insieme a eventuali opzioni necessarie. L’esempio seguente mostra come inserire un campo TC nel documento utilizzando DocumentBuilder.
Modificare un sommario
La formattazione delle voci nel TOC non utilizza gli stili originali delle voci contrassegnate, invece ogni livello è formattato utilizzando uno stile TOC equivalente. Ad esempio il primo livello nel TOC è formattato con lo stile TOC1, il secondo livello formattato con lo stile TOC2 e così via. Ciò significa che per cambiare l’aspetto del TOC è necessario modificare questi stili. In Aspose.Words questi stili sono rappresentati dal StyleIdentifier.TOC1 indipendente dalle impostazioni locali fino a StyleIdentifier.TOC9 e possono essere recuperati dalla raccolta Document.styles utilizzando questi identificatori.
Una volta recuperato lo stile appropriato del documento, è possibile modificare la formattazione di questo stile. Qualsiasi modifica a questi stili si rifletterà automaticamente nei sommari del documento. L’esempio seguente modifica una proprietà di formattazione utilizzata nello stile TOC di primo livello.
È inoltre utile notare che qualsiasi formattazione diretta di un paragrafo (definita nel paragrafo stesso e non nello stile) contrassegnata per essere inclusa nel TOC verrà copiata nella voce del TOC. Ad esempio, se lo stile Titolo 1 viene utilizzato per contrassegnare il contenuto del TOC e questo stile ha la formattazione in grassetto mentre al paragrafo viene applicata direttamente anche la formattazione corsivo. La voce TOC risultante non sarà in grassetto poiché fa parte della formattazione dello stile, tuttavia sarà in corsivo poiché è formattata direttamente nel paragrafo.
Puoi anche controllare la formattazione dei separatori utilizzati tra ogni voce e numero di pagina. Per impostazione predefinita si tratta di una linea tratteggiata che si estende lungo la numerazione delle pagine utilizzando un carattere di tabulazione e un punto di tabulazione destro allineato vicino al margine destro.
Utilizzando la classe Style recuperata per il particolare livello TOC che desideri modificare, puoi anche modificare il modo in cui questi appaiono nel documento. Per modificare il modo in cui appare, è necessario innanzitutto richiamare Style.paragraph_format per recuperare la formattazione del paragrafo per lo stile. Da questo è possibile recuperare i punti di tabulazione chiamando ParagraphFormat.tab_stops e modificare il punto di tabulazione appropriato. Utilizzando questa stessa tecnica la scheda stessa può essere spostata o rimossa tutta insieme. L’esempio seguente mostra come modificare la posizione della tabulazione destra nei paragrafi relativi a TOC.
Rimuovere un sommario dal documento
Un sommario può essere rimosso dal documento rimuovendo tutti i nodi trovati tra il nodo FieldStart e FieldEnd del campo TOC. Il codice seguente lo dimostra. La rimozione del campo TOC è più semplice di un campo normale in quanto non teniamo traccia dei campi nidificati. Controlliamo invece che il nodo FieldEnd sia di tipo FieldType.FIELD_TOC, il che significa che abbiamo incontrato la fine del sommario corrente. Questa tecnica può essere utilizzata in questo caso senza preoccuparsi dei campi nidificati poiché possiamo supporre che qualsiasi documento formato correttamente non avrà un campo TOC completamente nidificato all’interno di un altro campo TOC.
Innanzitutto vengono raccolti e archiviati i nodi FieldStart di ciascun TOC. Il TOC specificato viene quindi enumerato in modo che tutti i nodi all’interno del campo vengano visitati e archiviati. I nodi vengono quindi rimossi dal documento. L’esempio Below code dimostra come rimuovere un TOC specificato da un documento.
Estrai il sommario
Se si desidera estrarre un sommario da qualsiasi documento di Word, è possibile utilizzare il seguente esempio di codice.
doc = aw.Document(docs_base.my_dir + "Table of contents.docx")
for field in doc.range.fields :
if (field.type == aw.fields.FieldType.FIELD_HYPERLINK) :
hyperlink = field.as_field_hyperlink()
if (hyperlink.sub_address != None and hyperlink.sub_address.find("_Toc") == 0) :
tocItem = field.start.get_ancestor(aw.NodeType.PARAGRAPH).as_paragraph()
print(tocItem.to_string(aw.SaveFormat.TEXT).strip())
print("------------------")
bm = doc.range.bookmarks.get_by_name(hyperlink.sub_address)
pointer = bm.bookmark_start.get_ancestor(aw.NodeType.PARAGRAPH).as_paragraph()
print(pointer.to_string(aw.SaveFormat.TEXT))