Trabajar con tabla de contenidos
A menudo trabajará con documentos que contienen una tabla de contenido (TOC). Usando Aspose.Words puedes insertar tu propia tabla de contenido o reconstruir completamente la tabla de contenido existente en el documento usando solo unas pocas líneas de código. Este artículo describe cómo trabajar con el campo de tabla de contenido y demuestra:
- Cómo insertar un
TOCnuevo - Actualizar TOC nuevos o existentes en el documento.
- Especificar interruptores para controlar el formato y la estructura general del TOC.
- Cómo modificar los estilos y apariencia del índice.
- Cómo eliminar un campo
TOCcompleto junto con todas las entradas del documento.
Insertar una tabla de contenido mediante programación
Puede insertar un campo TOC (tabla de contenido) en el documento en la posición actual llamando al método DocumentBuilder.insert_table_of_contents.
Una tabla de contenido en un documento de Word se puede crear de varias maneras y formatearse usando una variedad de opciones. Los cambios de campo que pasa al método controlan la forma en que se construye y muestra la tabla en su documento.
Los modificadores predeterminados que se utilizan en un TOC insertado en Microsoft Word son "\o “1-3 \h \z \u”. Las descripciones de estos conmutadores, así como una lista de conmutadores compatibles, se pueden encontrar más adelante en el artículo. Puede usar esa guía para obtener los interruptores correctos o, si ya tiene un documento que contiene el TOC similar que desea, puede mostrar los códigos de campo (ALT+F9) y copiar los interruptores directamente desde el campo.
El siguiente ejemplo de código muestra cómo insertar un campo de tabla de contenido en un documento:
El código muestra la nueva tabla de contenido que se inserta en un documento en blanco. Luego, la clase DocumentBuilder se usa para insertar algún formato de contenido de muestra con los estilos de encabezado apropiados que se usan para marcar el contenido que se incluirá en el TOC. Las siguientes líneas luego completan el TOC actualizando los campos y el diseño de página del documento.
TOC, pero sin contenido visible. Esto se debe a que el campo TOC se insertó pero aún no se completa hasta que se actualice en el documento. Más información sobre esto se analiza en la siguiente sección.
Actualizar la tabla de contenidos
Aspose.Words le permite actualizar completamente un TOC con sólo unas pocas líneas de código. Esto se puede hacer para completar un TOC recién insertado o para actualizar un TOC existente después de que se hayan realizado cambios en el documento. Se deben utilizar los dos métodos siguientes para actualizar los campos TOC en el documento:
Tenga en cuenta que es necesario llamar a estos dos métodos de actualización en ese orden. Si se invierte, se completará la tabla de contenidos pero no se mostrarán los números de página. Se puede actualizar cualquier cantidad de TOC diferentes. Estos métodos actualizarán automáticamente todos los TOC que se encuentran en el documento.
El siguiente ejemplo de código muestra cómo reconstruir completamente los campos TOC en el documento invocando la actualización de campos:
La primera llamada a Document.update_fields creará el TOC, se completarán todas las entradas de texto y el TOC aparecerá casi completo. Lo único que falta son los números de página que por ahora se muestran con “?”. La segunda llamada a Document.update_page_layout creará el diseño del documento en la memoria. Esto debe hacerse para recopilar los números de página de las entradas. Los números de página correctos calculados a partir de esta llamada luego se insertan en el TOC.
Utilice interruptores para controlar el comportamiento de la tabla de contenidos.
Al igual que con cualquier otro campo, el campo TOC puede aceptar modificadores definidos dentro del código de campo que controlan cómo se construye la tabla de contenido. Ciertos interruptores se utilizan para controlar qué entradas se incluyen y en qué nivel, mientras que otros se utilizan para controlar la apariencia del TOC. Los interruptores se pueden combinar entre sí para permitir la producción de índices complejos.
De forma predeterminada, estos modificadores anteriores se incluyen al insertar un TOC predeterminado en el documento. Un TOC sin modificadores incluirá contenido de los estilos de encabezado integrados (como si el modificador \O estuviera configurado). Los conmutadores TOC disponibles que son compatibles con Aspose.Words se enumeran a continuación y sus usos se describen en detalle. Se pueden dividir en secciones separadas según su tipo. Los interruptores de la primera sección definen qué contenido incluir en el TOC y los interruptores de la segunda sección controlan la apariencia del TOC. Si un interruptor no aparece aquí, entonces no es compatible actualmente. Todos los conmutadores serán compatibles en versiones futuras. Estamos agregando más soporte con cada lanzamiento.
Interruptores de marcado de entrada
| Cambiar | Descripción |
|---|---|
| Heading Styles (\O Cambiar) |
Este modificador define que el |
Cualquier contenido formateado con estos estilos se incluye en la tabla de contenido. El nivel del encabezado definirá el nivel jerárquico correspondiente de la entrada en el TOC. Por ejemplo, un párrafo con el estilo Título 1 se tratará como el primer nivel en el `TOC`, mientras que un párrafo con el estilo Título 2 se tratará como el siguiente nivel en la jerarquía y así sucesivamente.
| | **Outline Levels***(\U interruptor)* |
Cada párrafo puede definir un nivel de esquema en Opciones de párrafo.
Esta configuración dicta en qué nivel se debe tratar este párrafo en la jerarquía del documento. Esta es una práctica comúnmente utilizada para estructurar fácilmente el diseño de un documento. Esta jerarquía se puede ver cambiando a Vista de esquema en Microsoft Word. De manera similar a los estilos de título, puede haber de 1 a 9 niveles de esquema además del nivel "Cuerpo del texto". Los niveles de esquema 1 a 9 aparecerán en el `TOC` en el nivel correspondiente de la jerarquía.
Cualquier contenido con un nivel de esquema establecido en el estilo de párrafo o directamente en el párrafo mismo se incluye en el TOC. En Aspose.Words, el nivel de esquema está representado por la propiedad `ParagraphFormat.OutlineLevel` del nodo Párrafo. El nivel de esquema de un estilo de párrafo se representa de la misma manera mediante la propiedad `Style.ParagraphFormat`.
Tenga en cuenta que los estilos de título integrados, como el Título 1, tienen un nivel de esquema establecido obligatoriamente en la configuración de estilo.
*(\T cambiar)* |
Este cambio permitirá que se utilicen estilos personalizados al recopilar entradas que se utilizarán en el TOC. Esto se usa a menudo junto con el interruptor \O para incluir estilos personalizados junto con estilos de encabezado integrados en el TOC.
Los parámetros del interruptor deben estar encerrados entre marcas de voz. Se pueden incluir muchos estilos personalizados; para cada estilo se debe especificar el nombre seguido de una coma seguida del nivel en el que debe aparecer el estilo en el `TOC`. Otros estilos también están separados por comas.
Por ejemplo
{ TOC \o "1-3" \t "CustomHeading1, 1, CustomHeading2, 2"}
utilizará contenido diseñado con CustomHeading1 como contenido de nivel 1 en `TOC` y CustomHeading2 como nivel 2.
| | **Use TC Fields***(Conmutadores \F y \L)* |
En versiones anteriores de Microsoft Word, la única forma de crear un `TOC` era mediante el uso de campos TC. Estos campos se insertan ocultos en el documento incluso cuando se muestran los códigos de campo. Incluyen el texto que debe mostrarse en la entrada y el `TOC` se construye a partir de ellos. Esta funcionalidad ahora no se usa con mucha frecuencia, pero aún puede ser útil en algunas ocasiones para incluir entradas en el `TOC` que no tienen sangría para ser visibles en el documento.
Cuando se insertan, estos campos aparecen ocultos incluso cuando se muestran los códigos de campo. No se pueden ver sin mostrar contenido oculto. Para ver estos campos se debe seleccionar Mostrar formato de párrafo.
Estos campos se pueden insertar en un documento en cualquier posición como cualquier otro campo y están representados por la enumeración `FieldType.FieldTOCEntry`.El modificador \F en un `TOC` se usa para especificar que los campos TC deben usarse como entradas. El cambio por sí solo sin ningún identificador adicional significa que se incluirá cualquier campo TC en el documento. Cualquier parámetro adicional, a menudo una sola letra, indicará que solo los campos TC que tengan un modificador \f coincidente se incluirán en el TOC. Por ejemplo *
{ TOC \f t }
sólo incluirá campos TC como
{ TC \f t }
El campo `TOC` también tiene un interruptor relacionado, el interruptor "\L" especifica que solo se incluye el campo TC con niveles dentro del rango especificado.
Los propios campos `TC` también pueden tener varios interruptores configurados. Estos son:
- *\F – Explicado arriba.*
- *\L: define en qué nivel del `TOC` aparecerá este campo TC. Un `TOC` que utilice este mismo interruptor solo incluirá este campo TC si está dentro del rango especificado.*
- `_\N`: la numeración de página para esta entrada `TOC` no se muestra. En la siguiente sección se puede encontrar un código de muestra sobre cómo insertar campos TC.
|Interruptores relacionados con la apariencia
| Cambiar | Descripción |
|---|---|
| Omit Page Numbers (\N Cambiar) |
Este interruptor se utiliza para ocultar números de página para ciertos niveles del TOC. Por ejemplo puedes definir |
{TOC \o "1-4" \n "3-4" }
y los números de página de las entradas de los niveles 3 y cuatro se ocultarán junto con los puntos guía (si los hay). Para especificar solo un nivel, aún se debe usar un rango; por ejemplo, "1-1" excluirá los números de página solo para el primer nivel.
Si no proporciona ningún rango de niveles, se omitirán los números de página de todos los niveles del TOC. Es útil configurar esto al exportar un documento a HTML o formato similar. Esto se debe a que los formatos basados en HTML no tienen ningún concepto de página y, por lo tanto, no necesitan ninguna numeración de páginas.
| | **Insert As Hyperlinks***(\H Cambiar)* |
Este modificador especifica que las entradas `TOC` se insertan como hipervínculos. Al ver un documento en Microsoft Word, estas entradas seguirán apareciendo como texto normal dentro del `TOC`, pero tienen hipervínculos y, por lo tanto, se pueden usar para navegar a la posición de la entrada original en el documento usando *Ctrl + clic izquierdo* en Microsoft Word. Cuando se incluye este modificador, estos enlaces también se conservan en otros formatos. Por ejemplo, en formatos basados en HTML, incluidos EPUB y formatos renderizados como PDF y XPS, estos se exportarán como enlaces de trabajo.
Sin este interruptor configurado, el `TOC` en todas estas salidas se exportará como texto sin formato y no demostrará este comportamiento. Si se abre un documento en MS Word, tampoco se podrá hacer clic en el texto de las entradas de esta manera, pero aún se podrán usar los números de página para navegar a la entrada original.
PELEA
| | **Set Separator Character***(\P Cambiar)* |
Este interruptor permite cambiar fácilmente el contenido que separa el título de la entrada y la numeración de página en el TOC. El separador a utilizar debe especificarse después de este cambio y encerrarse entre marcas de voz.
Al contrario de lo documentado en la documentación de Office, sólo se puede utilizar un carácter en lugar de hasta cinco. Esto se aplica tanto a MS Word como a Aspose.Words.
No se recomienda el uso de este interruptor ya que no permite mucho control sobre lo que se usa para separar entradas y números de página en el TOC. En su lugar, se recomienda editar el estilo `TOC` apropiado, como `StyleIdentifier.TOC1`, y desde allí editar el estilo líder con acceso a miembros de fuente específicos, etc. Se pueden encontrar más detalles sobre cómo hacer esto más adelante en el artículo.
PELEA
| | **Preserve Tab Entries***(\W Cambiar)* |
El uso de este modificador especificará que cualquier entrada que tenga un carácter de tabulación, por ejemplo un encabezado que tenga una tabulación al final de la línea, se conservará como un carácter de tabulación adecuado al completar el TOC. Esto significa que la función del carácter de tabulación estará presente en el `TOC` y se puede utilizar para formatear la entrada. Por ejemplo, ciertas entradas pueden usar tabulaciones y caracteres de tabulación para espaciar uniformemente el texto. Siempre que el nivel `TOC` correspondiente defina las tabulaciones equivalentes, las entradas `TOC` generadas aparecerán con espacios similares.
En la misma situación, si este interruptor no estuviera definido, los caracteres de tabulación se convertirían en espacios en blanco equivalentes a pestañas que no funcionan. Entonces el resultado no aparecería como se esperaba.
| | **Preserve New Line Entries***(\X Cambiar)* |
De manera similar al cambio anterior, este cambio especifica que los títulos que abarcan varias líneas (usando caracteres de nueva línea, no párrafos separados) se conservarán tal como están en el TOC generado. Por ejemplo, un encabezado que debe abarcar varias líneas puede utilizar el carácter de nueva línea (Ctrl + Enter o `ControlChar.LineBreak`) para separar el contenido en diferentes líneas. Con este modificador especificado, la entrada en el `TOC` conservará estos caracteres de nueva línea como se muestra a continuación.
En esta situación, si el interruptor no está definido, los caracteres de nueva línea se convierten en un único espacio en blanco.
|Insertar campos de CT
Puede insertar un nuevo campo TC en la posición actual del DocumentBuilder llamando al método DocumentBuilder.insert_field y especificando el nombre del campo como “TC” junto con los modificadores que sean necesarios. El siguiente ejemplo muestra cómo insertar un campo TC en el documento usando DocumentBuilder.
Modificar una tabla de contenido
El formato de las entradas en TOC no utiliza los estilos originales de las entradas marcadas, sino que cada nivel se formatea utilizando un estilo TOC equivalente. Por ejemplo, el primer nivel del TOC está formateado con el estilo TOC1, el segundo nivel con el estilo TOC2, etc. Esto significa que para cambiar el aspecto del TOC se deben modificar estos estilos. En Aspose.Words, estos estilos están representados desde StyleIdentifier.TOC1 independiente de la configuración regional hasta StyleIdentifier.TOC9 y se pueden recuperar de la colección Document.styles utilizando estos identificadores.
Una vez que se ha recuperado el estilo apropiado del documento, se puede modificar el formato de este estilo. Cualquier cambio en estos estilos se reflejará automáticamente en los TOC del documento. El siguiente ejemplo cambia una propiedad de formato utilizada en el estilo TOC de primer nivel.
También es útil tener en cuenta que cualquier formato directo de un párrafo (definido en el párrafo mismo y no en el estilo) marcado para incluirse en TOC se copiará en la entrada del TOC. Por ejemplo, si el estilo Título 1 se usa para marcar contenido para TOC y este estilo tiene formato de negrita mientras que el párrafo también tiene formato de cursiva aplicado directamente. La entrada TOC resultante no estará en negrita ya que es parte del formato de estilo, sin embargo estará en cursiva ya que está formateada directamente en el párrafo.
También puede controlar el formato de los separadores utilizados entre cada entrada y número de página. De forma predeterminada, se trata de una línea de puntos que se extiende a lo largo de la numeración de páginas mediante un carácter de tabulación y una tabulación derecha alineada cerca del margen derecho.
Usando la clase Style recuperada para el nivel TOC particular que desea modificar, también puede modificar cómo aparecen en el documento. Para cambiar cómo aparece esto, primero se debe llamar a Style.paragraph_format para recuperar el formato de párrafo para el estilo. A partir de aquí, las tabulaciones se pueden recuperar llamando a ParagraphFormat.tab_stops y modificando la tabulación adecuada. Usando esta misma técnica, la pestaña se puede mover o quitar por completo. El siguiente ejemplo muestra cómo modificar la posición de la tabulación derecha en párrafos relacionados con TOC.
Eliminar una tabla de contenido del documento
Se puede eliminar una tabla de contenido del documento eliminando todos los nodos que se encuentran entre el nodo FieldStart y FieldEnd del campo TOC. El siguiente código demuestra esto. La eliminación del campo TOC es más sencilla que la de un campo normal, ya que no realizamos un seguimiento de los campos anidados. En lugar de eso, verificamos que el nodo FieldEnd sea de tipo FieldType.FIELD_TOC, lo que significa que hemos encontrado el final del TOC actual. Esta técnica se puede utilizar en este caso sin preocuparse por los campos anidados, ya que podemos suponer que cualquier documento formado correctamente no tendrá ningún campo TOC completamente anidado dentro de otro campo TOC.
En primer lugar se recopilan y almacenan los nodos FieldStart de cada TOC. Luego, el TOC especificado se enumera para que todos los nodos dentro del campo sean visitados y almacenados. Luego, los nodos se eliminan del documento. El ejemplo Below code demuestra cómo eliminar un TOC específico de un documento.
Extraer tabla de contenidos
Si desea extraer una tabla de contenido de cualquier documento de Word, puede utilizar el siguiente ejemplo de código.
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))