Bookmarks

Bookmarks

Это руководство показывает, как читать, вставлять, переходить к и удалять закладки в документе Word с помощью Aspose.Words FOSS для .NET. Закладка отмечает именованное место или диапазон контента, чтобы его можно было найти, перейти к нему или использовать в качестве точки вставки для дальнейших правок. Aspose.Words FOSS для .NET представляет закладки с помощью классов Bookmark, BookmarkStart и BookmarkEnd, и предоставляет методы DocumentBuilder для создания и поиска их при написании или редактировании документа.

Чтение закладок

Каждый Range раскрывает содержащиеся в нём закладки через свойство Bookmarks, которое возвращает BookmarkCollection. Поскольку Document сам раскрывает Range, doc.Range.Bookmarks возвращает каждую закладку в документе. Найдите конкретную закладку по имени с помощью индексатора BookmarkCollection — bookmarks[bookmarkName] — проверьте, сколько их существует с помощью Count, или пройдитесь по всей коллекции с помощью GetEnumerator(). Каждый Bookmark раскрывает свой Name и заключённый в нём текст через Text.

Вставка закладок с помощью DocumentBuilder

DocumentBuilder — обычный способ создания закладок при написании документа. Вызовите StartBookmark(bookmarkName) перед вставкой контента, затем EndBookmark(bookmarkName) после него — построитель оборачивает всё написанное между ними как диапазон закладки. Для диапазона столбцов таблицы используйте вместо этого StartColumnBookmark(bookmarkName) и EndColumnBookmark(bookmarkName); полученный Bookmark.IsColumn будет true, при этом FirstColumn и LastColumn определяют отмеченный диапазон столбцов. Чтобы переместить построитель к существующей закладке для дальнейших правок, вызовите MoveToBookmark(bookmarkName) или перегрузку MoveToBookmark(bookmarkName, isStart, isAfter), чтобы управлять тем, к какому концу закладки будет перемещён курсор.

Структура закладок в дереве документа

Закладка представлена в дереве документа как пара узлов: BookmarkStart и BookmarkEnd, оба построены как BookmarkStart(doc, name) / BookmarkEnd(doc, name). Каждый ссылается на свой логический объект Bookmark — BookmarkStart.Bookmark возвращает его, а Bookmark в свою очередь предоставляет свойства BookmarkStart и BookmarkEnd, указывающие на два граничных узла. Поскольку BookmarkStart и BookmarkEnd являются обычными узлами, они поддерживают стандартные операции над узлами, такие как GetText(), Clone(isCloneChildren) и GetAncestor(ancestorType), и могут быть найдены обходом дерева, как любой другой тип узла.

Удаление закладок

Вызовите Bookmark.Remove(), чтобы удалить начальный и конечный маркеры одной закладки — это удаляет саму закладку, а не содержимое документа, которое она охватывает. Чтобы удалить закладки массово, используйте BookmarkCollection.Remove(bookmark), Remove(bookmarkName), RemoveAt(index) или Clear(), чтобы сразу удалить все закладки в указанном диапазоне.

Советы и лучшие практики

• Предпочитайте индексатор BookmarkCollection (bookmarks["BookmarkName"]) вместо ручной итерации, когда вы уже знаете имя целевой закладки.
• Всегда сочетайте вызов StartBookmark(name) с соответствующим вызовом EndBookmark(name), используя то же имя — несоответствующая пара оставит закладку неполной.
• Проверьте Bookmark.IsColumn перед чтением FirstColumn или LastColumn — эти два свойства имеют смысл только для колонковых закладок, созданных с помощью StartColumnBookmark/EndColumnBookmark.
• Bookmark.Remove() удаляет только маркеры закладки, а не вложенный текст, поэтому удаление закладки никогда не удаляет содержимое документа.
• Используйте DocumentBuilder.MoveToBookmark(), чтобы переместить курсор построителя в известное место, вместо того чтобы вручную искать в дереве узлов BookmarkStart.

Распространённые проблемы

FAQ

Как получить все закладки в документе?

Прочитайте doc.Range.Bookmarks, который возвращает BookmarkCollection, охватывающий весь документ.

Можно ли закладкой отметить часть таблицы по столбцу, а не по диапазону текста?

Да — используйте DocumentBuilder.StartColumnBookmark(bookmarkName) и EndColumnBookmark(bookmarkName). Полученная закладка имеет IsColumn, установленный в true, а FirstColumn/LastColumn обозначают диапазон столбцов.

Удаляет ли удаление закладки текст, который она отмечает?

№ Bookmark.Remove() удаляет только узлы маркеров BookmarkStart/BookmarkEnd; содержимое документа между ними остаётся нетронутым.

Как переместить курсор DocumentBuilder к существующей закладке?

Вызовите DocumentBuilder.MoveToBookmark(bookmarkName) или MoveToBookmark(bookmarkName, isStart, isAfter), чтобы контролировать, будет ли курсор помещён в начало или конец закладки.

В чём разница между перегрузками BookmarkCollection.Remove()?

Remove(bookmark) принимает объект Bookmark, Remove(bookmarkName) принимает его имя, а RemoveAt(index) принимает его позицию в коллекции — все три удаляют одну закладку, тогда как Clear() удаляет все закладки в коллекции.

API Reference Сводка

См. также:

• Aspose.Words for .NET — Enterprise Documentation