Bookmarks

Bookmarks

Esta guía muestra cómo leer, insertar, navegar a y eliminar marcadores en un documento de Word con Aspose.Words FOSS para .NET. Un marcador indica una ubicación nombrada o un rango de contenido para que pueda ser buscado, navegado o usado como punto de inserción para ediciones posteriores. Aspose.Words FOSS para .NET representa los marcadores con las clases Bookmark, BookmarkStart y BookmarkEnd, y proporciona métodos DocumentBuilder para crear y localizar los mismos al redactar o editar un documento.

Leyendo Marcadores

Cada Range expone los marcadores que contiene a través de la propiedad Bookmarks, que devuelve un BookmarkCollection. Dado que Document mismo expone un Range, doc.Range.Bookmarks devuelve todos los marcadores del documento. Busca un marcador específico por nombre con el indexador BookmarkCollection — bookmarks[bookmarkName] — verifica cuántos existen con Count, o recorre toda la colección con GetEnumerator(). Cada Bookmark expone su Name y el texto que encierra a través de Text.

Insertando Marcadores con DocumentBuilder

DocumentBuilder es la forma habitual de crear marcadores mientras se escribe un documento. Llama a StartBookmark(bookmarkName) antes de insertar contenido, luego a EndBookmark(bookmarkName) después — el constructor envuelve todo lo escrito entre ambos como el rango marcado. Para un rango de columnas de tabla, usa StartColumnBookmark(bookmarkName) y EndColumnBookmark(bookmarkName) en su lugar; el Bookmark.IsColumn resultante es true, con FirstColumn y LastColumn que identifican el rango de columnas marcado. Para reposicionar el constructor en un marcador existente para ediciones posteriores, llama a MoveToBookmark(bookmarkName), o a la sobrecarga MoveToBookmark(bookmarkName, isStart, isAfter) para controlar en qué extremo del marcador queda el cursor.

Estructura de Marcadores en el Árbol del Documento

Un marcador se representa en el árbol del documento como un par de nodos: BookmarkStart y BookmarkEnd, ambos construidos como BookmarkStart(doc, name) / BookmarkEnd(doc, name). Cada uno enlaza de vuelta a su objeto lógico Bookmark — BookmarkStart.Bookmark lo devuelve, y Bookmark a su vez expone las propiedades BookmarkStart y BookmarkEnd que apuntan a sus dos nodos límite. Dado que BookmarkStart y BookmarkEnd son nodos ordinarios, admiten las operaciones estándar de nodo como GetText(), Clone(isCloneChildren) y GetAncestor(ancestorType), y pueden localizarse recorriendo el árbol como cualquier otro tipo de nodo.

Eliminar marcadores

Llame a Bookmark.Remove() para eliminar los marcadores de inicio y fin de un único marcador — esto elimina el propio marcador, no el contenido del documento que encierra. Para eliminar marcadores en bloque, use BookmarkCollection.Remove(bookmark), Remove(bookmarkName), RemoveAt(index) o Clear() para suprimir todos los marcadores del rango de una vez.

Consejos y mejores prácticas

• Prefiera el indexador BookmarkCollection (bookmarks["BookmarkName"]) sobre la iteración manual cuando ya conoce el nombre del marcador objetivo.
• Siempre combine una llamada a StartBookmark(name) con una llamada correspondiente a EndBookmark(name) usando el mismo nombre — una pareja no coincidente deja el marcador incompleto.
• Verifique Bookmark.IsColumn antes de leer FirstColumn o LastColumn — esas dos propiedades solo tienen sentido para los marcadores de columna creados con StartColumnBookmark/EndColumnBookmark.
• Bookmark.Remove() elimina solo los marcadores del marcador, no el texto incluido, por lo que eliminar un marcador nunca borra el contenido del documento.
• Utilice DocumentBuilder.MoveToBookmark() para mover el cursor del constructor a una ubicación conocida en lugar de buscar manualmente el árbol de nodos para un BookmarkStart.

Problemas comunes

FAQ

¿Cómo obtengo todos los marcadores en un documento?

Lea doc.Range.Bookmarks, que devuelve un BookmarkCollection que cubre todo el documento.

¿Puedo marcar parte de una tabla por columna en lugar de por rango de texto?

Sí — use DocumentBuilder.StartColumnBookmark(bookmarkName) y EndColumnBookmark(bookmarkName). El marcador resultante tiene IsColumn establecido en true, con FirstColumn/LastColumn marcando el rango de columnas.

¿Eliminar un marcador borra el texto que marca?

No. Bookmark.Remove() elimina solo los nodos marcador BookmarkStart/BookmarkEnd; el contenido del documento entre ellos queda sin tocar.

¿Cómo muevo el cursor DocumentBuilder a un marcador existente?

Llame a DocumentBuilder.MoveToBookmark(bookmarkName), o MoveToBookmark(bookmarkName, isStart, isAfter) para controlar si el cursor se posiciona al inicio o al final del marcador.

¿Cuál es la diferencia entre las sobrecargas de BookmarkCollection.Remove()?

Remove(bookmark) recibe un objeto Bookmark, Remove(bookmarkName) recibe su nombre, y RemoveAt(index) recibe su posición en la colección — los tres eliminan un único marcador, mientras que Clear() elimina todos los marcadores de la colección.

API Reference Resumen

Ver también

• Aspose.Words for .NET — Enterprise Documentation