Bookmarks

Bookmarks

Este guia mostra como ler, inserir, navegar até e remover marcadores em um documento Word com Aspose.Words FOSS para .NET. Um marcador indica um local nomeado ou um intervalo de conteúdo para que possa ser consultado, navegado ou usado como ponto de inserção para edições adicionais. Aspose.Words FOSS para .NET representa marcadores com as classes Bookmark, BookmarkStart e BookmarkEnd, e fornece métodos DocumentBuilder para criar e localizar esses marcadores ao autorar ou editar um documento.

Lendo Marcadores

Cada Range expõe os marcadores que contém através da propriedade Bookmarks, que devolve um BookmarkCollection. Como Document por si só expõe um Range, doc.Range.Bookmarks devolve todos os marcadores no documento. Consulte um marcador específico pelo nome com o indexador BookmarkCollection — bookmarks[bookmarkName] — verifique quantos existem com Count, ou percorra toda a coleção com GetEnumerator(). Cada Bookmark expõe seu Name e o texto que engloba através de Text.

Inserindo Marcadores com DocumentBuilder

DocumentBuilder é a forma usual de criar marcadores ao redigir um documento. Chame StartBookmark(bookmarkName) antes de inserir conteúdo, depois EndBookmark(bookmarkName) após ele — o construtor envolve tudo escrito entre eles como o intervalo marcado. Para um intervalo de colunas de tabela, use StartColumnBookmark(bookmarkName) e EndColumnBookmark(bookmarkName) em vez disso; o Bookmark.IsColumn resultante é true, com FirstColumn e LastColumn identificando o intervalo de colunas marcado. Para reposicionar o construtor em um marcador existente para edições adicionais, chame MoveToBookmark(bookmarkName), ou a sobrecarga MoveToBookmark(bookmarkName, isStart, isAfter) para controlar em qual extremidade do marcador o cursor se posiciona.

Estrutura de Marcadores na Árvore do Documento

Um bookmark é representado na árvore do documento como um par de nós: BookmarkStart e BookmarkEnd, ambos construídos como BookmarkStart(doc, name) / BookmarkEnd(doc, name). Cada um vincula de volta ao seu objeto lógico Bookmark — BookmarkStart.Bookmark o retorna, e Bookmark por sua vez expõe as propriedades BookmarkStart e BookmarkEnd apontando para seus dois nós de limite. Como BookmarkStart e BookmarkEnd são nós comuns, eles suportam as operações padrão de nó, como GetText(), Clone(isCloneChildren) e GetAncestor(ancestorType), e podem ser localizados percorrendo a árvore como qualquer outro tipo de nó.

Removendo Marcadores

Chame Bookmark.Remove() para excluir os marcadores de início e fim de um único bookmark — isso remove apenas o bookmark, não o conteúdo do documento que ele engloba. Para remover bookmarks em massa, use BookmarkCollection.Remove(bookmark), Remove(bookmarkName), RemoveAt(index) ou Clear() para descartar todos os bookmarks no intervalo de uma só vez.

Dicas e Melhores Práticas

• Prefira o indexador BookmarkCollection (bookmarks["BookmarkName"]) em vez de iteração manual quando você já souber o nome do bookmark de destino.
• Sempre emparelhe uma chamada StartBookmark(name) com uma chamada EndBookmark(name) correspondente usando o mesmo nome — um par não correspondido deixa o bookmark incompleto.
• Verifique Bookmark.IsColumn antes de ler FirstColumn ou LastColumn — essas duas propriedades só têm significado para bookmarks de coluna criados com StartColumnBookmark/EndColumnBookmark.
• Bookmark.Remove() exclui apenas os marcadores do bookmark, não o texto incluído, portanto remover um bookmark nunca exclui o conteúdo do documento.
• Use DocumentBuilder.MoveToBookmark() para mover o cursor do construtor para um local conhecido em vez de procurar manualmente na árvore de nós por um BookmarkStart.

Problemas Comuns

FAQ

Como obter todos os marcadores em um documento?

Leia doc.Range.Bookmarks, que retorna um BookmarkCollection que cobre todo o documento.

Posso marcar parte de uma tabela por coluna em vez de por intervalo de texto?

Sim — use DocumentBuilder.StartColumnBookmark(bookmarkName) e EndColumnBookmark(bookmarkName). O marcador resultante tem IsColumn definido como true, com FirstColumn/LastColumn marcando o intervalo de colunas.

Remover um marcador exclui o texto que ele marca?

Obs. Bookmark.Remove() remove apenas os nós marcador BookmarkStart/BookmarkEnd; o conteúdo do documento entre eles permanece intacto.

Como mover o cursor DocumentBuilder para um marcador existente?

Chame DocumentBuilder.MoveToBookmark(bookmarkName) ou MoveToBookmark(bookmarkName, isStart, isAfter) para controlar se o cursor pousa no início ou no final do marcador.

Qual é a diferença entre as sobrecargas de BookmarkCollection.Remove()?

Remove(bookmark) recebe um objeto Bookmark, Remove(bookmarkName) recebe seu nome e RemoveAt(index) recebe sua posição na coleção — os três removem um único marcador, enquanto Clear() remove todos os marcadores da coleção.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation