Trabalhar com índice
Muitas vezes, você trabalhará com documentos contendo um índice (TOC). Usando Aspose.Words você pode inserir seu próprio índice ou reconstruir completamente o índice existente no documento usando apenas algumas linhas de código.
Este artigo descreve como trabalhar com o campo índice e demonstra:
- Como inserir um novo TOC.
- Actualizar TOCs novo ou existente no documento.
- Especifique as opções para controlar a formatação e a estrutura geral do TOC.
- Como modificar os estilos e a aparência do Índice.
- Como remover um campo
TOC
inteiro juntamente com todas as entradas do documento.
Inserir o índice programaticamente
Você pode inserir um campo TOC
(índice) no documento na posição atual chamando o método InsertTableOfContents.
Um índice em um documento do Word pode ser construído de várias maneiras e formatado usando uma variedade de opções. As opções de campo que passa para o método controlam a forma como a tabela é criada e apresentada no documento.
Os switches padrão que são usados em um TOC
inserido em Microsoft Word são "\o “1-3 \h \z \u”. As descrições desses switches, bem como uma lista de switches suportados, podem ser encontradas posteriormente no artigo. Você pode usar esse guia para obter os switches corretos ou, se já tiver um documento contendo o TOC
semelhante que deseja, pode mostrar os códigos de campo (ALT+F9) e copiar os switches diretamente do campo.
O exemplo de código a seguir mostra como inserir um campo de índice em um documento:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
Document doc = new Document(); | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// Insert a table of contents at the beginning of the document. | |
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u"); | |
// The newly inserted table of contents will be initially empty. | |
// It needs to be populated by updating the fields in the document. | |
doc.updateFields(); | |
doc.save(dataDir + "InsertATableOfContentsField_out.docx"); |
O exemplo de código a seguir demonstra como inserir um sumário (TOC) em um documento usando estilos de título como entradas:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
Document doc = new Document(); | |
// Create a document builder to insert content with into document. | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// Insert a table of contents at the beginning of the document. | |
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u"); | |
// Start the actual document content on the second page. | |
builder.insertBreak(BreakType.PAGE_BREAK); | |
// Build a document with complex structure by applying different heading styles thus creating TOC entries. | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1); | |
builder.writeln("Heading 1"); | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2); | |
builder.writeln("Heading 1.1"); | |
builder.writeln("Heading 1.2"); | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1); | |
builder.writeln("Heading 2"); | |
builder.writeln("Heading 3"); | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2); | |
builder.writeln("Heading 3.1"); | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3); | |
builder.writeln("Heading 3.1.1"); | |
builder.writeln("Heading 3.1.2"); | |
builder.writeln("Heading 3.1.3"); | |
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2); | |
builder.writeln("Heading 3.2"); | |
builder.writeln("Heading 3.3"); | |
// Call the method below to update the TOC. | |
doc.updateFields(); | |
doc.save(dataDir + "InsertATableOfContentsUsingHeadingStyles_out.docx"); |
O código demonstra que o novo índice é inserido num documento em branco. A classe DocumentBuilder é então usada para inserir alguns exemplos de formatação de conteúdo com os estilos de título apropriados que são usados para marcar o conteúdo a ser incluído no TOC. As próximas linhas preenchem o TOC
Atualizando os campos e o layout da página do documento.
TOC
, mas sem conteúdo visível. Isso ocorre porque o campo TOC
foi inserido, mas ainda não foi preenchido até que seja atualizado no documento. Mais informações sobre este assunto são discutidas na próxima secção.
Actualizar o índice
Aspose.Words permite atualizar completamente a TOC
com apenas algumas linhas de código. Isso pode ser feito para preencher um TOC
recém-inserido ou para atualizar um TOC
existente após as alterações no documento terem sido feitas.
Os dois métodos a seguir devem ser usados para atualizar os campos TOC
no documento:
Observe que esses dois métodos de atualização devem ser chamados nessa ordem. Se invertido, o índice será preenchido, mas não serão apresentados números de página. Qualquer número de diferentes TOCs pode ser atualizado. Esses métodos atualizarão automaticamente todos os TOCs encontrados no documento.
O exemplo de código a seguir mostra como reconstruir completamente TOC
campos no documento invocando atualizações de campo:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
doc.updateFields(); |
A primeira chamada para Document.updateFields() irá construir o TOC
, Todas as entradas de texto são preenchidas e o TOC
aparece quase completo. A única coisa que falta são os números de página que, por enquanto, são exibidos com “?”.
A segunda chamada para Document.updatePageLayout() irá construir o layout do documento na memória. Isto tem de ser feito para recolher os números das páginas das entradas. Os números de página corretos calculados a partir desta chamada são então inseridos no TOC.
Usar opções para controlar o comportamento do Índice
Como acontece com qualquer outro campo, o campo TOC
pode aceitar opções definidas no código do campo que controla como o índice é construído. Alguns interruptores são utilizados para controlar quais entradas estão incluídas e em que nível, enquanto outros são utilizados para controlar a aparência do TOC. Os interruptores podem ser combinados para permitir a produção de um índice complexo.
Por padrão, essas opções acima são incluídas ao inserir um TOC
padrão no documento. A TOC
sem opções incluirá conteúdo dos estilos de título integrados (como se a opção \O estivesse definida).
Os switches TOC
disponíveis que são suportados por Aspose.Words estão listados abaixo e seus usos são descritos em detalhes. Eles podem ser divididos em seções separadas com base em seu tipo. Os comutadores na primeira secção definem o conteúdo a incluir no TOC
e os comutadores na segunda secção controlam a aparência do TOC.
Se um switch não estiver listado aqui, ele não será suportado no momento. Todos os switches serão suportados em versões futuras. Estamos a acrescentar mais apoio a cada lançamento.
Interruptores De Marcação De Entrada
Interruptor | Descrição |
---|---|
Heading Styles * (\O Interruptor)* |
Esta opção define que o
|
Outline Levels * (Interruptor \ U)* |
Cada parágrafo Pode definir um nível de esboço em Opções de parágrafo.
Observe que os estilos de cabeçalho integrados, como Heading 1, têm um nível de contorno obrigatório definido nas configurações de estilo.
|
Custom Styles * (Interruptor \ T)* |
Essa opção permitirá que estilos personalizados sejam usados ao coletar entradas a serem usadas no TOC. Isso é frequentemente usado em conjunto com a opção \O para incluir estilos personalizados junto com estilos de cabeçalho integrados no TOC.
usará conteúdo estilizado com CustomHeading1 como conteúdo de Nível 1 no |
Utilizar TC Campos * (Interruptores\F E \L)* |
Em versões mais antigas de Microsoft Word, a única maneira de construir um Estes campos podem ser inseridos num documento em qualquer posição como qualquer outro campo e são representados pela enumeração
incluirá apenas TC campos como
O campo
– \ F-explicado acima. – \ L-define em qual nível no - |
Interruptores Relacionados Com A Aparência
Interruptor | Descrição |
---|---|
Omit Page Numbers * (Interruptor\N)* |
Esta opção é utilizada para ocultar números de página para determinados níveis do TOC. Por exemplo, você pode definir
e os números das páginas nas entradas dos níveis 3 e quatro serão ocultados juntamente com os pontos principais (Se houver). Para especificar apenas um nível, deve continuar a ser utilizado um intervalo, por exemplo, “1-1” excluirá os números de página apenas para o primeiro nível. |
Inserir Como Hiperligações * (Interruptor \ H)* |
Esta opção especifica que as entradas |
Set Separator Character * (Interruptor\P)* |
Esta opção permite que o conteúdo que separa o título da entrada e a numeração da página seja facilmente alterado no TOC. O separador a utilizar deve ser especificado após este interruptor e colocado em marcas de fala. |
Preserve Tab Entries * (Interruptor \ W)* |
O uso desta opção especificará que quaisquer entradas que tenham um caractere de tabulação, por exemplo, um título que tenha uma tabulação no final da linha, serão mantidas como um caractere de tabulação adequado ao preencher o TOC. Isso significa que a função do caractere tab estará presente no |
Preserve New Line Entries * (\X Interruptor)* |
Semelhante à opção acima, essa opção especifica que os títulos que abrangem várias linhas (usando caracteres de nova linha, não parágrafos separados) serão preservados como estão no TOC gerado. Por exemplo, um título que deve ser espalhado por várias linhas pode usar o novo caractere de linha (Ctrl + Enter ou |
Inserir TC Campos
Você pode inserir um novo campo TC na posição atual do DocumentBuilder
chamando o método DocumentBuilder.InsertField
e especificando o nome do campo como “TC” junto com quaisquer opções necessárias.
O exemplo de código a seguir mostra como inserir um campo TC
no documento usando DocumentBuilder.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
Document doc = new Document(); | |
// Create a document builder to insert content with. | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// Insert a TC field at the current document builder position. | |
builder.insertField("TC \"Entry Text\" \\f t"); |
Muitas vezes, uma linha de texto específica é designada para o TOC
e é marcada com um campo TC
. A maneira mais fácil de fazer isso em MS Word é destacar o texto e pressionar ALT+SHIFT+O. Isso cria automaticamente um campo TC
usando o texto selecionado. A mesma técnica pode ser realizada através do Código. O código abaixo irá encontrar o texto correspondente à entrada e inserir um campo TC
na mesma posição que o texto. O código baseia-se na mesma técnica utilizada no artigo. O exemplo de código a seguir mostra como localizar e inserir um campo TC
no texto de um documento.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
class InsertTCFieldHandler implements IReplacingCallback { | |
// Store the text and switches to be used for the TC fields. | |
private String mFieldText; | |
private String mFieldSwitches; | |
/** | |
* The switches to use for each TC field. Can be an empty string or null. | |
*/ | |
public InsertTCFieldHandler(String switches) throws Exception { | |
this(null, switches); | |
} | |
/** | |
* The display text and the switches to use for each TC field. Display text | |
* Can be an empty string or null. | |
*/ | |
public InsertTCFieldHandler(String text, String switches) throws Exception { | |
mFieldText = text; | |
mFieldSwitches = switches; | |
} | |
public int replacing(ReplacingArgs args) throws Exception { | |
// Create a builder to insert the field. | |
DocumentBuilder builder = new DocumentBuilder((Document) args.getMatchNode().getDocument()); | |
// Move to the first node of the match. | |
builder.moveTo(args.getMatchNode()); | |
// If the user specified text to be used in the field as display text then use that, otherwise use the | |
// match string as the display text. | |
String insertText; | |
if (!(mFieldText == null || "".equals(mFieldText))) | |
insertText = mFieldText; | |
else | |
insertText = args.getMatch().group(); | |
// Insert the TC field before this node using the specified string as the display text and user defined switches. | |
builder.insertField(java.text.MessageFormat.format("TC \"{0}\" {1}", insertText, mFieldSwitches)); | |
// We have done what we want so skip replacement. | |
return ReplaceAction.SKIP; | |
} | |
} |
Modificar um índice
Alterar a formatação dos estilos
A formatação das entradas no TOC
não usa os estilos originais das entradas marcadas, em vez disso, cada nível é formatado usando um estilo TOC
equivalente. Por exemplo, o primeiro nível no TOC
é formatado com o estilo TOC1, o segundo nível formatado com o estilo TOC2 e assim por diante. Isso significa que, para alterar a aparência do TOC
, esses estilos devem ser modificados. Em Aspose.Words, esses estilos são representados pela localidade independente StyleIdentifier.TOC1
até StyleIdentifier.TOC9
e podem ser recuperados da coleção Document.Styles
usando esses identificadores.
Uma vez recuperado o estilo apropriado do documento, a formatação deste estilo pode ser modificada. Quaisquer alterações a estes estilos serão automaticamente refletidas no TOCs do documento.
O exemplo de código a seguir altera uma propriedade de formatação usada no estilo TOC
de primeiro nível.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
public static void changeAFormattingPropertyUsedInFirstLevelTOCStyle() throws Exception { | |
Document doc = new Document(); | |
// Retrieve the style used for the first level of the TOC and change the formatting of the style. | |
doc.getStyles().getByStyleIdentifier(StyleIdentifier.TOC_1).getFont().setBold(true); | |
} |
Também é útil notar que qualquer formatação direta de um parágrafo (definido no próprio parágrafo e não no estilo) marcado para ser incluído no TOC
será copiado na entrada no TOC. Por exemplo, se o estilo Heading 1 for usado para marcar o conteúdo para o TOC
e este estilo tiver formatação em negrito, enquanto o parágrafo também tiver formatação em itálico aplicada diretamente a ele. A entrada TOC
resultante não será em negrito, pois faz parte da formatação de estilo, mas será em itálico, pois está formatada diretamente no parágrafo.
Também pode controlar a formatação dos separadores utilizados entre cada entrada e o número da página. Por padrão, trata-se de uma linha pontilhada que é espalhada até a numeração da página usando um caractere de tabulação e uma parada de tabulação direita alinhada perto da margem direita.
Usando a classe Style
recuperada para o nível TOC
específico que você deseja modificar, Você também pode modificar como elas aparecem no documento.
Para alterar a forma como isso aparece, em primeiro lugar, Style.ParagraphFormat
deve ser chamado para recuperar a formatação do parágrafo para o estilo. A partir disso, as paradas de tabulação podem ser recuperadas chamando ParagraphFormat.TabStops
e a parada de tabulação apropriada modificada. Usando esta mesma técnica, a guia em si pode ser movida ou removida completamente.
O exemplo de código a seguir mostra como modificar a posição da tabulação direita em TOC
parágrafos relacionados.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
public static void modifyPositionOfRightTabStopInTOC() throws Exception { | |
Document doc = new Document(dataDir + "Field.TableOfContents.doc"); | |
// Iterate through all paragraphs in the document | |
for (Paragraph para : (Iterable<Paragraph>) doc.getChildNodes(NodeType.PARAGRAPH, true)) { | |
// Check if this paragraph is formatted using the TOC result based styles. This is any style between TOC and TOC9. | |
if (para.getParagraphFormat().getStyle().getStyleIdentifier() >= StyleIdentifier.TOC_1 && para.getParagraphFormat().getStyle().getStyleIdentifier() <= StyleIdentifier.TOC_9) { | |
// Get the first tab used in this paragraph, this should be the tab used to align the page numbers. | |
TabStop tab = para.getParagraphFormat().getTabStops().get(0); | |
// Remove the old tab from the collection. | |
para.getParagraphFormat().getTabStops().removeByPosition(tab.getPosition()); | |
// Insert a new tab using the same properties but at a modified position. | |
// We could also change the separators used (dots) by passing a different Leader type | |
para.getParagraphFormat().getTabStops().add(tab.getPosition() - 50, tab.getAlignment(), tab.getLeader()); | |
} | |
} | |
doc.save(dataDir + "Field.TableOfContentsTabStops_Out.doc"); | |
} |
Remover um índice do documento
Um índice pode ser removido do documento removendo todos os nós encontrados entre os nós FieldStart
e FieldEnd do campo TOC
.
O código abaixo demonstra isso. A remoção do campo TOC
é mais simples do que um campo normal, pois não acompanhamos os campos aninhados. Em vez disso, verificamos que o nó FieldEnd
é do tipo FieldType.FieldTOC
, o que significa que encontramos o fim do TOC atual. Esta técnica pode ser usada neste caso sem se preocupar com quaisquer campos aninhados, pois podemos assumir que qualquer documento devidamente formado não terá um campo TOC
totalmente aninhado dentro de outro campo TOC
.
Em primeiro lugar, os nós FieldStart
de cada TOC
são recolhidos e armazenados. O TOC
especificado é então enumerado para que todos os nós dentro do campo sejam visitados e armazenados. Os nós são então removidos do documento. O exemplo de código a seguir demonstra como remover um TOC
especificado de um documento.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
// Open a document which contains a TOC. | |
Document doc = new Document(dataDir + "Document.TableOfContents.doc"); | |
// Remove the first table of contents from the document. | |
removeTableOfContents(doc, 0); | |
// Save the output. | |
doc.save(dataDir + "Document.TableOfContentsRemoveToc_Out.doc"); |
Extrair Índice
Se pretender extrair um sumário de qualquer documento do Word, pode utilizar-se o seguinte exemplo de código.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
// The path to the documents directory. | |
String dataDir = Utils.getSharedDataDir(ExtractTableOfContents.class) + "TableOfContents/"; | |
String fileName = "TOC.doc"; | |
Document doc = new Document(dataDir + fileName); | |
for (Field field : (Iterable<Field>)doc.getRange().getFields()) | |
{ | |
if (field.getType() == FieldType.FIELD_HYPERLINK) | |
{ | |
FieldHyperlink hyperlink = (FieldHyperlink)field; | |
if (hyperlink.getSubAddress() != null && hyperlink.getSubAddress().startsWith("_Toc")) | |
{ | |
Paragraph tocItem = (Paragraph)field.getStart().getAncestor(NodeType.PARAGRAPH); | |
System.out.println(tocItem.toString(SaveFormat.TEXT).trim()); | |
System.out.println("------------------"); | |
if (tocItem != null) | |
{ | |
Bookmark bm = doc.getRange().getBookmarks().get(hyperlink.getSubAddress()); | |
// Get the location this TOC Item is pointing to | |
Paragraph pointer = (Paragraph)bm.getBookmarkStart().getAncestor(NodeType.PARAGRAPH); | |
System.out.println(pointer.toString(SaveFormat.TEXT)); | |
} | |
} // End If | |
}// End If | |
}// End Foreach |