Bookmarks

Bookmarks

Questa guida mostra come leggere, inserire, navigare verso e rimuovere i segnalibri in un documento Word con Aspose.Words FOSS per .NET. Un segnalibro indica una posizione nominata o un intervallo di contenuto in modo che possa essere ricercato, raggiunto o utilizzato come punto di inserimento per ulteriori modifiche. Aspose.Words FOSS per .NET rappresenta i segnalibri con le classi Bookmark, BookmarkStart e BookmarkEnd, e fornisce i metodi DocumentBuilder per crearli e individuarli durante la creazione o la modifica di un documento.

Lettura dei segnalibri

Ogni Range espone i segnalibri che contiene tramite la proprietà Bookmarks, che restituisce un BookmarkCollection. Poiché Document stessa espone un Range, doc.Range.Bookmarks restituisce tutti i segnalibri nel documento. Cerca un segnalibro specifico per nome con l’indicizzatore BookmarkCollection — bookmarks[bookmarkName] — verifica quanti ne esistono con Count, o percorri l’intera collezione con GetEnumerator(). Ogni Bookmark espone il suo Name e il testo che racchiude tramite Text.

Inserimento di segnalibri con DocumentBuilder

DocumentBuilder è il metodo consueto per creare segnalibri durante la scrittura di un documento. Chiama StartBookmark(bookmarkName) prima di inserire il contenuto, poi EndBookmark(bookmarkName) dopo di esso — il costruttore avvolge tutto ciò che è scritto in mezzo come intervallo segnalato. Per un intervallo di colonne di tabella, usa invece StartColumnBookmark(bookmarkName) e EndColumnBookmark(bookmarkName); il Bookmark.IsColumn risultante è true, con FirstColumn e LastColumn che identificano l’intervallo di colonne contrassegnato. Per riposizionare il costruttore su un segnalibro esistente per ulteriori modifiche, chiama MoveToBookmark(bookmarkName), o la sovraccarico MoveToBookmark(bookmarkName, isStart, isAfter) per controllare a quale estremità del segnalibro il cursore si posizioni.

Struttura dei segnalibri nell’albero del documento

Un segnalibro è rappresentato nell’albero del documento come una coppia di nodi: BookmarkStart e BookmarkEnd, entrambi costruiti come BookmarkStart(doc, name) / BookmarkEnd(doc, name). Ognuno collega al suo oggetto Bookmark logico — BookmarkStart.Bookmark lo restituisce, e Bookmark a sua volta espone le proprietà BookmarkStart e BookmarkEnd che puntano ai suoi due nodi di confine. Poiché BookmarkStart e BookmarkEnd sono nodi ordinari, supportano le operazioni standard sui nodi come GetText(), Clone(isCloneChildren) e GetAncestor(ancestorType), e possono essere individuati percorrendo l’albero come qualsiasi altro tipo di nodo.

Rimuovere i segnalibri

Chiama Bookmark.Remove() per eliminare i marcatori di inizio e fine di un singolo segnalibro — questo rimuove il segnalibro stesso, non il contenuto del documento che racchiude. Per rimuovere i segnalibri in blocco, usa BookmarkCollection.Remove(bookmark), Remove(bookmarkName), RemoveAt(index) o Clear() per eliminare tutti i segnalibri nell’intervallo in una volta.

Suggerimenti e migliori pratiche

• Preferisci l’indicizzatore BookmarkCollection (bookmarks["BookmarkName"]) rispetto all’iterazione manuale quando conosci già il nome del segnalibro target.
• Associa sempre una chiamata StartBookmark(name) a una corrispondente chiamata EndBookmark(name) usando lo stesso nome — una coppia non corrispondente lascia il segnalibro incompleto.
• Verifica Bookmark.IsColumn prima di leggere FirstColumn o LastColumn — quelle due proprietà sono significative solo per i segnalibri di colonna creati con StartColumnBookmark/EndColumnBookmark.
• Bookmark.Remove() elimina solo i marcatori del segnalibro, non il testo racchiuso, quindi rimuovere un segnalibro non elimina mai il contenuto del documento.
• Usa DocumentBuilder.MoveToBookmark() per spostare il cursore del builder a una posizione nota invece di cercare manualmente nell’albero dei nodi un BookmarkStart.

Problemi comuni

FAQ

Come ottengo tutti i segnalibri in un documento?

Leggi doc.Range.Bookmarks, che restituisce un BookmarkCollection che copre l’intero documento.

Posso creare un segnalibro di una parte di una tabella per colonna invece che per intervallo di testo?

Sì — usa DocumentBuilder.StartColumnBookmark(bookmarkName) e EndColumnBookmark(bookmarkName). Il segnalibro risultante ha IsColumn impostato su true, con FirstColumn/LastColumn che indicano l’intervallo di colonne.

La rimozione di un segnalibro elimina il testo che contrassegna?

No. Bookmark.Remove() rimuove solo i nodi marcatore BookmarkStart/BookmarkEnd; il contenuto del documento tra di essi rimane intatto.

Come sposto il cursore DocumentBuilder a un segnalibro esistente?

Chiama DocumentBuilder.MoveToBookmark(bookmarkName), o MoveToBookmark(bookmarkName, isStart, isAfter) per controllare se il cursore si posiziona all’inizio o alla fine del segnalibro.

Qual è la differenza tra le overload BookmarkCollection.Remove()?

Remove(bookmark) accetta un oggetto Bookmark, Remove(bookmarkName) ne accetta il nome e RemoveAt(index) ne accetta la posizione nella collezione — tutti e tre rimuovono un singolo segnalibro, mentre Clear() rimuove tutti i segnalibri nella collezione.

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation