使用书签

书签在 Microsoft Word 文档中标识您命名和标识的位置或片段，以供将来参考。例如，您可以使用书签来标识稍后要修改的文本。您可以使用"书签"对话框转到文本，而不是滚动文档来查找文本。

使用 Aspose.Words 对书签执行的操作与使用 Microsoft Word 执行的操作相同。您可以插入新书签、删除、移动到书签、获取或设置书签名称、获取或设置其中包含的文本。使用 Aspose.Words，您还可以在报告或文档中使用书签，将一些数据插入书签或对其内容应用特殊格式。您还可以使用书签从文档中的特定位置检索文本。

插入书签

使用 start_bookmark 和 end_bookmark 分别通过标记其开始和结束来创建书签。不要忘记将相同的书签名称传递给这两个方法。文档中的书签可以重叠并跨越任何范围。保存文档时，格式错误的书签或名称重复的书签将被忽略。

书签中的所有空格均替换为下划线。此限制来自 MS Word 格式，因为 MS Word 格式中的书签（如 DOCX 或 DOC）不能包含空格。然而，PDF 允许这样的书签。因此，现在，如果您需要在 PDF 或 XPS 大纲中使用书签，则可以将它们与空格一起使用。

以下代码示例展示了如何创建新书签：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.start_bookmark("My Bookmark")
builder.writeln("Text inside a bookmark.")

builder.start_bookmark("Nested Bookmark")
builder.writeln("Text inside a NestedBookmark.")
builder.end_bookmark("Nested Bookmark")

builder.writeln("Text after Nested Bookmark.")
builder.end_bookmark("My Bookmark")

options = aw.saving.PdfSaveOptions()
options.outline_options.bookmarks_outline_levels.add("My Bookmark", 1)
options.outline_options.bookmarks_outline_levels.add("Nested Bookmark", 2)

doc.save(docs_base.artifacts_dir + "WorkingWithBookmarks.create_bookmark.pdf", options)

获取书签

有时需要获取书签集合以迭代书签或用于其他目的。使用任何文档节点公开的 Node.range 属性，该属性返回表示该节点中包含的文档部分的 Range 对象。使用此对象检索 BookmarkCollection，然后使用集合索引器获取特定书签。

您可以从 Aspose.Words GitHub 下载这些示例的示例文件。

以下代码示例演示如何从书签集合中获取书签：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Bookmarks.docx")
    
# By index:
bookmark1 = doc.range.bookmarks[0]
# By name:
bookmark2 = doc.range.bookmarks.get_by_name("MyBookmark3")

以下代码示例显示如何获取或设置书签名称和文本：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Bookmarks.docx")

bookmark = doc.range.bookmarks.get_by_name("MyBookmark1")

name = bookmark.name
text = bookmark.text

bookmark.name = "RenamedBookmark"
bookmark.text = "This is a new bookmarked text."

以下代码示例显示如何为表添加书签：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.start_table()
    
builder.insert_cell()

builder.start_bookmark("MyBookmark")

builder.write("This is row 1 cell 1")

builder.insert_cell()
builder.write("This is row 1 cell 2")

builder.end_row()

builder.insert_cell()
builder.writeln("This is row 2 cell 1")

builder.insert_cell()
builder.writeln("This is row 2 cell 2")

builder.end_row()
builder.end_table()
    
builder.end_bookmark("MyBookmark")

如果将书签名称更改为文档中已存在的名称，则保存文档时不会产生错误，并且只会存储第一个书签。

请注意，文档中的某些书签已分配给表单字段。移动到这样的书签并在其中插入文本会将文本插入表单字段代码中。虽然这不会使表单字段无效，但插入的文本将不可见，因为它成为字段代码的一部分。

以下代码示例显示如何访问已添加书签的表的列：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
for bookmark in doc.range.bookmarks :
    
    print("Bookmark: " + bookmark.name + " (Column)" if bookmark.is_column else "")

    if (bookmark.is_column) :
        
        row = bookmark.bookmark_start.get_ancestor(aw.NodeType.ROW).as_row() 
        if (bookmark.first_column < row.cells.count) :
            print(row.cells[bookmark.first_column].get_text().trim_end(aw.ControlChar.CELL_CHAR))
        
    

移至书签

如果需要在书签中插入丰富的内容（不仅仅是纯文本），则应使用 move_to_bookmark 将光标移动到书签，然后使用 DocumentBuilder’s 方法和属性插入内容。

显示隐藏书签内容

整个书签（包括加书签的内容）可以使用 Aspose.Words 封装在 IF 字段的 True 部分中。可以这样的方式，IF字段在表达式(操作符的左边)中包含嵌套的合并字段，并且根据合并字段的值，IF字段显示或隐藏Word文档中书签的内容。

以下代码示例展示了如何显示/隐藏书签：

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Bookmarks.docx")

self.show_hide_bookmarked_content(doc, "MyBookmark1", False)
    
doc.save(docs_base.artifacts_dir + "WorkingWithBookmarks.show_hide_bookmarks.docx")

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
@staticmethod
def show_hide_bookmarked_content(doc : aw.Document, bookmarkName : str, showHide : bool) :
    
    bm = doc.range.bookmarks.get_by_name(bookmarkName)

    builder = aw.DocumentBuilder(doc)
    builder.move_to_document_end()

    # IF "MERGEFIELD bookmark" = "True" "" ""
    field = builder.insert_field("IF \"", None)
    builder.move_to(field.start.next_sibling)
    builder.insert_field("MERGEFIELD " + bookmarkName + "", None)
    builder.write("\" = \"True\" ")
    builder.write("\"")
    builder.write("\"")
    builder.write(" \"\"")

    currentNode = field.start
    flag = True
    while (currentNode != None and flag) :
        
        if (currentNode.node_type == aw.NodeType.RUN) :
            if (currentNode.to_string(aw.SaveFormat.TEXT).strip() == "\"") :
                flag = False

        nextNode = currentNode.next_sibling

        bm.bookmark_start.parent_node.insert_before(currentNode, bm.bookmark_start)
        currentNode = nextNode
        

    endNode = bm.bookmark_end
    flag = True
    while (currentNode != None and flag) :
        
        if (currentNode.node_type == aw.NodeType.FIELD_END) :
            flag = False

        nextNode = currentNode.next_sibling

        bm.bookmark_end.parent_node.insert_after(currentNode, endNode)
        endNode = currentNode
        currentNode = nextNode
        

    doc.mail_merge.execute([ bookmarkName ], [ showHide ])