Lavorare con i campi Index e Tables

Lavorare con i campi Indice e Tabelle

Questa guida mostra come lavorare con la famiglia di campi “Index and Tables” di Word — i campi alla base di un indice, di un indice analitico, di una tabella delle figure e di una tabella delle autorità. Ognuno di questi è una sottoclasse Field nello spazio dei nomi Aspose.Words.Fields: FieldToc (indice o figure), FieldIndex (indice analitico), FieldXE (voce di indice), FieldToa (tabella delle autorità), FieldTA (voce della tabella delle autorità, o citazione), FieldTC (voce dell’indice), e FieldRD (documento di riferimento, per creare un indice o un indice combinato su più file).

La classe base del campo

Ogni classe di campo in questa famiglia eredita da Field, che espone Start, Separator e End (i nodi FieldStart, FieldSeparator e FieldEnd che delimitano il campo nel flusso di run), Type (un valore FieldType — FieldTOC, FieldIndex, FieldTOA, FieldTOCEntry, FieldIndexEntry, FieldTOAEntry o FieldRefDoc per questa famiglia), Result/DisplayResult (il testo attualmente calcolato del campo), IsLocked e IsDirty, e i metodi GetFieldCode(), Update(), Unlink() e Remove(). Update() ricalcola il risultato del campo; per un indice, ciò significa ricostruire l’elenco delle voci dalle intestazioni del documento o dai marcatori FieldTC.

Inserire un indice

DocumentBuilder.InsertTableOfContents(switches) inserisce un FieldToc nella posizione corrente del costruttore, usando una stringa di switch di campo Word (ad esempio "\o \"1-3\" \h \z \u") per controllare quali livelli di intestazione sono inclusi e come è formattato il risultato — gli stessi switch che Word scrive quando si inserisce un indice tramite l’interfaccia. Una volta inserito, FieldToc.UpdatePageNumbers() ricalcola la parte del numero di pagina delle voci esistenti. FieldToc espone inoltre proprietà che controllano direttamente la struttura dell’indice: HeadingLevelRange e EntryLevelRange (quali livelli di outline sono inclusi), EntryIdentifier (l’identificatore del campo TC che l’indice deve raccogliere, per creare più indici da diversi marcatori FieldTC), InsertHyperlinks, PreserveTabs/PreserveLineBreaks, EntrySeparator/SequenceSeparator, BookmarkName, e — per una tabella delle figure anziché un indice — TableOfFiguresLabel e CaptionlessTableOfFiguresLabel.

Contrassegnare voci personalizzate dell’indice

Non ogni voce del TOC proviene da uno stile di intestazione. FieldTC segna una posizione specifica come voce dell’indice dei contenuti indipendente dallo stile di paragrafo: FieldTC.Text è il testo della voce, EntryLevel è il livello di struttura in cui dovrebbe apparire, TypeIdentifier la collega a un FieldToc.EntryIdentifier quando si creano più TOC, e OmitPageNumber sopprime il numero di pagina per quella voce.

Creare un indice

FieldIndex implementa il campo INDEX, che raccoglie i marcatori FieldXE (voce di indice) di un documento in un indice alfabetico. FieldXE.Text è il testo della voce, EntryType raggruppa le voci in sotto-livelli usando una sintassi separata da due punti, PageRangeBookmarkName segna un segnalibro la cui estensione diventa un intervallo di pagine nell’indice anziché un singolo numero di pagina, e IsBold/IsItalic formattano il riferimento di pagina risultante. Sul lato FieldIndex, Heading inserisce separatori a capo lettera (A, B, C…), LetterRange limita l’indice a un sottoinsieme dell’alfabeto, RunSubentriesOnSameLine controlla la disposizione delle sotto-voci, e PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator controllano la punteggiatura tra una voce e il suo riferimento di pagina. FieldIndexFormat elenca separatamente gli stili visivi di indice integrati in Word (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).

Tavola delle autorità

FieldToa e FieldTA sono l’equivalente delle autorità di FieldIndex/FieldXE: FieldTA segna una citazione nel testo (LongCitation e ShortCitation testo, EntryCategory per raggrupparla sotto un’intestazione come “Casi” o “Statuti”, e IsBold/IsItalic per la formattazione), e FieldToa raccoglie quelle citazioni in una tavola, con EntryCategory che seleziona quale categoria compilare, UseHeading e UsePassim che controllano le intestazioni di categoria e la convenzione “passim” per le fonti citate molte volte, e PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting che controllano il layout.

Riferire contenuti da altri documenti

FieldRD implementa il campo RD, che indica a un campo TOC, indice o tavola delle autorità di includere voci da un altro file durante la compilazione — FieldRD.FileName è il documento di riferimento, e IsPathRelative controlla se quel percorso viene risolto in modo relativo al documento corrente.

Suggerimenti e migliori pratiche

Crea la stringa di commutazione del TOC allo stesso modo in cui lo fa Word (\o "1-3" \h \z \u) invece di configurare singolarmente ogni proprietà FieldToc, quindi modifica solo le proprietà specifiche che devi cambiare successivamente.
Chiama FieldToc.UpdatePageNumbers() (o Field.Update()) dopo le modifiche al contenuto affinché un TOC, un indice o una tabella delle autorità rifletta il documento corrente invece di risultati obsoleti da quando è stato inserito.
Usa FieldTC.TypeIdentifier insieme a FieldToc.EntryIdentifier quando un documento richiede più di un TOC (ad esempio un TOC principale e una tabella delle figure separata) costruiti da diversi insiemi di voci.
Imposta FieldXE.PageRangeBookmarkName (o il contrassegno di intervallo equivalente di FieldTA) invece di formattare manualmente un intervallo di pagine nel testo della voce, così l’indice/tabella rimane coerente se il contenuto si sposta.
Ricorda che i numeri di pagina nei risultati INDEX/TOC/TOA di questa edizione sono valutati come valori segnaposto anziché come numeri di pagina reali, poiché l’impaginazione e la paginazione non fanno parte di questa edizione.

Problemi comuni

Problema	Causa	Correzione
Una tabella dei contenuti non include le intestazioni previste	La stringa di switch del TOC (o `HeadingLevelRange`) esclude quei livelli di outline	Regola gli switch passati a `InsertTableOfContents` o imposta `FieldToc.HeadingLevelRange`
Una voce di indice non appare dove previsto	Il marcatore `FieldXE` corrispondente è mancante, o la sua sintassi di sottolivello `EntryType` non corrisponde a ciò che `FieldIndex` si aspetta	Conferma che i marcatori `FieldXE` esistono e che i loro valori `EntryType` siano formattati in modo coerente
I risultati del campo sembrano obsoleti dopo aver modificato il contenuto	Il campo non è stato aggiornato dopo la modifica	Chiama `Update()` sul campo (o `UpdateFields()` sul `Document`)
Le voci di un altro documento non vengono incluse durante la compilazione	Nessun `FieldRD` che faccia riferimento a quel documento esiste, o `IsPathRelative` non corrisponde a come il percorso dovrebbe risolversi	Aggiungi un `FieldRD` con le corrette impostazioni `FileName` e `IsPathRelative`

FAQ

Come inserire un indice programmaticamente?

Chiama DocumentBuilder.InsertTableOfContents(switches) con una stringa di opzioni in stile Word, come "\o \"1-3\" \h \z \u", nella posizione in cui dovrebbe apparire il TOC.

Come contrassegnare il testo come voce di indice?

Inserisci un campo FieldXE in quella posizione (ad esempio tramite DocumentBuilder.InsertField) impostando la sua proprietà Text sul testo della voce; FieldIndex raccoglie tutti i marcatori FieldXE nel documento nel risultato dell’indice.

Qual è la differenza tra `FieldTC` e le voci di TOC basate sui titoli?

Il comportamento predefinito del TOC di Word raccoglie le voci dai paragrafi che utilizzano gli stili di titolo. FieldTC consente di contrassegnare una posizione arbitraria come voce di TOC indipendente dallo stile del paragrafo, che FieldToc può includere tramite valori corrispondenti EntryIdentifier/TypeIdentifier.

Come posso aggiornare un TOC o un indice dopo le modifiche al documento?

Chiama Update() sul campo specifico (ad esempio FieldToc.Update(), o FieldToc.UpdatePageNumbers() solo per i numeri di pagina), oppure Document.UpdateFields() per aggiornare tutti i campi nel documento.

Posso compilare un TOC o un indice su più documenti?

Sì — inserisci un campo FieldRD che punti a ciascun documento aggiuntivo tramite FileName; il campo di compilazione (FieldToc, FieldIndex o FieldToa) include le voci dai documenti di riferimento quando viene aggiornato.

API Reference Sommario

Classe/Metodo	Descrizione
`Field`	Classe base per tutti i tipi di campo, inclusi `Start`/`Separator`/`End`, `Type`, `Update()`
`DocumentBuilder.InsertTableOfContents(switches)`	Inserisci un `FieldToc` usando le opzioni TOC in stile Word
`FieldToc`	Implementa il campo TOC (indice dei contenuti o indice delle figure)
`FieldTC`	Segna una voce di indice personalizzata in una posizione specifica
`FieldIndex`	Implementa il campo INDEX, compilando i marcatori `FieldXE`
`FieldXE`	Segna una posizione come voce di indice
`FieldToa`	Implementa il campo table-of-authorities, compilando i marcatori `FieldTA`
`FieldTA`	Segna una citazione per una table of authorities
`FieldRD`	Fa riferimento al contenuto di un altro documento quando si compila un indice, un indice analitico o una tavola delle autorità
`FieldIndexFormat`	Enum degli stili visuali dell’indice integrati in Word

Vedi anche

Aspose.Words for .NET — Enterprise Documentation