Trabalhando com Campos de Índice e Tabelas

Trabalhando com Campos de Índice e Tabelas

Este guia mostra como trabalhar com a família de campos “Index and Tables” do Word — os campos por trás de um sumário, um índice, uma tabela de figuras e uma tabela de autoridades. Cada um desses é uma subclasse Field no namespace Aspose.Words.Fields: FieldToc (sumário ou figuras), FieldIndex (índice), FieldXE (entrada de índice), FieldToa (tabela de autoridades), FieldTA (entrada de tabela de autoridades, ou citação), FieldTC (entrada de sumário), e FieldRD (documento referenciado, para construir um índice ou sumário combinado em vários arquivos).

A Classe Base de Campo

Cada classe de campo nesta família herda de Field, que expõe Start, Separator e End (os nós FieldStart, FieldSeparator e FieldEnd que delimitam o campo no fluxo de execução), Type (um valor FieldType — FieldTOC, FieldIndex, FieldTOA, FieldTOCEntry, FieldIndexEntry, FieldTOAEntry ou FieldRefDoc para esta família), Result/DisplayResult (o texto atualmente computado do campo), IsLocked e IsDirty, e os métodos GetFieldCode(), Update(), Unlink() e Remove(). Update() recalcula o resultado do campo; para um sumário, isso significa reconstruir a lista de entradas a partir dos títulos do documento ou marcadores FieldTC.

Inserindo um Sumário

DocumentBuilder.InsertTableOfContents(switches) insere um FieldToc na posição atual do construtor, usando uma string de switches de campo do Word (por exemplo "\o \"1-3\" \h \z \u") para controlar quais níveis de títulos são incluídos e como o resultado é formatado — os mesmos switches que o Word grava ao inserir um sumário pela interface. Uma vez inserido, FieldToc.UpdatePageNumbers() recalcula a parte de número de página das entradas existentes. FieldToc também expõe propriedades que controlam a estrutura do sumário diretamente: HeadingLevelRange e EntryLevelRange (quais níveis de contorno são incluídos), EntryIdentifier (o identificador de campo TC que o sumário deve coletar, para construir múltiplos sumários a partir de diferentes marcadores FieldTC), InsertHyperlinks, PreserveTabs/PreserveLineBreaks, EntrySeparator/SequenceSeparator, BookmarkName, e — para uma tabela de figuras em vez de um sumário — TableOfFiguresLabel e CaptionlessTableOfFiguresLabel.

Marcando Entradas Personalizadas de Sumário

Nem toda entrada de TOC provém de um estilo de título. FieldTC marca um local específico como uma entrada de sumário independente do estilo de parágrafo: FieldTC.Text é o texto da entrada, EntryLevel é o nível de estrutura onde deve aparecer, TypeIdentifier a vincula a um FieldToc.EntryIdentifier ao criar mais de um TOC, e OmitPageNumber suprime o número da página para essa entrada.

Construindo um Índice

FieldIndex implementa o campo INDEX, que compila os marcadores de FieldXE (entrada de índice) de um documento em um índice alfabético. FieldXE.Text é o texto da entrada, EntryType agrupa entradas em subníveis usando sintaxe separada por dois-pontos, PageRangeBookmarkName marca um bookmark cujo alcance se torna um intervalo de páginas no índice em vez de um único número de página, e IsBold/IsItalic formatam a referência de página resultante. No lado FieldIndex, Heading insere separadores de letras (A, B, C…), LetterRange restringe o índice a um subconjunto do alfabeto, RunSubentriesOnSameLine controla o layout de sub-entradas, e PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator controlam a pontuação entre uma entrada e sua referência de página. FieldIndexFormat enumera separadamente os estilos visuais de índice incorporados ao Word (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).

Tabela de Autoridades

FieldToa e FieldTA são o equivalente de autoridades de FieldIndex/FieldXE: FieldTA marca uma citação no texto (LongCitation e ShortCitation texto, EntryCategory para agrupá-la sob um título como “Cases” ou “Statutes”, e IsBold/IsItalic para formatação), e FieldToa compila essas citações em uma tabela, com EntryCategory selecionando qual categoria compilar, UseHeading e UsePassim controlando os títulos das categorias e a convenção “passim” para fontes citadas muitas vezes, e PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting controlando o layout.

Referenciando Conteúdo de Outros Documentos

FieldRD implementa o campo RD, que indica a um campo de TOC, índice ou tabela de autoridades que inclua entradas de outro arquivo ao compilar — FieldRD.FileName é o documento referenciado, e IsPathRelative controla se esse caminho é resolvido relativo ao documento atual.

Dicas e Boas Práticas

• Construa a string de alternância do TOC da mesma forma que o Word faz (\o "1-3" \h \z \u) ao invés de configurar cada propriedade FieldToc individualmente, e então ajuste apenas as propriedades específicas que você precisa mudar depois.
• Chame FieldToc.UpdatePageNumbers() (ou Field.Update()) após alterações de conteúdo para que um TOC, índice ou tabela de autoridades reflita o documento atual ao invés de resultados desatualizados de quando foi inserido.
• Use FieldTC.TypeIdentifier juntamente com FieldToc.EntryIdentifier quando um documento precisar de mais de um TOC (por exemplo, um TOC principal e uma tabela de figuras separada) construído a partir de diferentes conjuntos de entradas.
• Defina FieldXE.PageRangeBookmarkName (ou a marcação de intervalo equivalente de FieldTA) em vez de formatar manualmente um intervalo de páginas no texto da entrada, para que o índice/tabela permaneça consistente se o conteúdo for movido.
• Lembre-se de que os números de página nos resultados de INDEX/TOC/TOA desta edição são avaliados como valores de espaço reservado, e não como números de página reais, pois o layout de página e a paginação não fazem parte desta edição.

Problemas comuns

FAQ

Como inserir um sumário programaticamente?

Chame DocumentBuilder.InsertTableOfContents(switches) com uma string de parâmetros no estilo do Word, como "\o \"1-3\" \h \z \u", na posição onde o TOC deve aparecer.

Como marcar texto como uma entrada de índice?

Insira um campo FieldXE naquele local (por exemplo via DocumentBuilder.InsertField) com sua propriedade Text definida para o texto da entrada; FieldIndex compila todos os marcadores FieldXE no documento no resultado do índice.

Qual é a diferença entre FieldTC e as entradas de TOC baseadas em títulos?

O comportamento padrão de TOC do Word coleta entradas de parágrafos que utilizam estilos de título. FieldTC permite marcar um local arbitrário como uma entrada de TOC independente do estilo de parágrafo, que FieldToc pode incluir por meio da correspondência dos valores EntryIdentifier/TypeIdentifier.

Como atualizo um TOC ou índice após alterações no documento?

Chame Update() no campo específico (por exemplo FieldToc.Update(), ou FieldToc.UpdatePageNumbers() apenas para números de página), ou Document.UpdateFields() para atualizar todos os campos no documento.

Posso compilar um TOC ou índice em vários documentos?

Sim — insira um campo FieldRD apontando para cada documento adicional via FileName; o campo de compilação (FieldToc, FieldIndex ou FieldToa) inclui entradas dos documentos referenciados quando é atualizado.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation