Bookmarks

Bookmarks

本指南展示了如何在使用 Aspose.Words FOSS for .NET 的 Word 文档中读取、插入、导航至以及删除书签。书签标记了一个具名位置或内容范围，以便可以查找、导航或用作进一步编辑的插入点。Aspose.Words FOSS for .NET 使用 Bookmark、BookmarkStart 和 BookmarkEnd 类来表示书签，并提供 DocumentBuilder 方法，以在创作或编辑文档时创建和定位书签。

读取书签

每个 Range 通过其 Bookmarks 属性公开其包含的书签，该属性返回一个 BookmarkCollection。由于 Document 本身公开了一个 Range，doc.Range.Bookmarks 返回文档中的所有书签。使用 BookmarkCollection 索引器（bookmarks[bookmarkName]）按名称查找特定书签——使用 Count 检查存在的数量，或使用 GetEnumerator() 遍历整个集合。每个 Bookmark 通过 Text 公开其 Name 和所包含的文本。

使用 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) 调用配对——未配对的调用会导致书签不完整。
• 在读取 FirstColumn 或 LastColumn 之前请检查 Bookmark.IsColumn——这两个属性仅对使用 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