插入字段

有几种不同的方法可以将字段插入到文档中：

• 使用DocumentBuilder
• 使用FieldBuilder
• 使用Aspose.Words Document Object Model (DOM)

在本文中，我们将更详细地了解每种方式，并分析如何使用这些选项插入某些字段。

使用 DocumentBuilder 将字段插入文档

在 Aspose.Words 中，insert_field 方法用于将新字段插入到文档中。第一个参数接受要插入的字段的完整字段代码。第二个参数是可选的，允许手动设置字段的字段结果。如果未提供此字段，则该字段会自动更新。您可以将 null 或empty 传递给此参数以插入具有空字段值的字段。如果您不确定特定的字段代码语法，请先在 Microsoft Word 中创建字段，然后切换以查看其字段代码。

如果您的字段代码有一个包含空格的参数，则必须将其括在语音标记内。否则，Microsoft Word 和 Aspose.Words 中的字段可能无法按预期工作，因为两者都将参数视为被截断。

以下代码示例演示如何使用 DocumentBuilder 将合并字段插入到文档中：

# 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.insert_field("MERGEFIELD MyFieldName \* MERGEFORMAT")
    
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_field.docx")

以下代码示例演示如何使用 DocumentBuilder 将具有德语区域设置的合并字段插入到文档中：

# 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)

# Insert content with German locale.
builder.font.locale_id = 1031
builder.insert_field("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\"")
builder.write(" - ")
builder.insert_field("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\"")

使用相同的技术来插入嵌套在其他字段中的字段。

以下代码示例演示如何使用 DocumentBuilder 插入嵌套在另一个字段中的字段：

# 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)

for i in range(0, 5) :
    builder.insert_break(aw.BreakType.PAGE_BREAK)

builder.move_to_header_footer(aw.HeaderFooterType.FOOTER_PRIMARY)

# We want to insert a field like this:
#  IF PAGE <> NUMPAGES "See Next Page" "Last Page" 
field = builder.insert_field("IF ")
builder.move_to(field.separator)
builder.insert_field("PAGE")
builder.write(" <> ")
builder.insert_field("NUMPAGES")
builder.write(" \"See Next Page\" \"Last Page\" ")

field.update()

doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_nested_fields.docx")

在字段级别指定区域设置

语言标识符是一个国家或地理区域的语言的标准国际数字缩写。使用 Aspose.Words，您可以在字段级别指定区域设置。 locale_id 属性获取或设置字段的区域设置 ID。

以下代码示例展示了如何使用此选项：

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

field = builder.insert_field(aw.fields.FieldType.FIELD_DATE, True)
field.locale_id = 1049
    
builder.document.save(docs_base.artifacts_dir + "WorkingWithFields.specifylocale_at_fieldlevel.docx")

插入无类型/空字段

如果您想像 Microsoft Word 允许的那样插入非类型化/空字段 ({})，您可以使用带有 FieldType.FIELD_NONE 参数的 insert_field 方法。要在 Word 文档中插入字段，可以按"Ctrl + F9"组合键。

以下代码示例展示了如何将空字段插入到文档中：

# 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)

field = builder.insert_field(aw.fields.FieldType.FIELD_NONE, False)

doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_field_none.docx")

使用 FieldBuilder 将字段插入到文档中

在 Aspose.Words 中插入字段的另一种方法是 FieldBuilder 类。它提供流畅的界面来指定字段开关和参数值作为文本、节点甚至嵌套字段。

以下代码示例演示如何使用 FieldBuilder 将字段插入到文档中：

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

# Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
field_builder = aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_IF)
field_builder.add_argument("left expression")
field_builder.add_argument("=")
field_builder.add_argument("right expression")
field_builder.add_argument(
    aw.fields.FieldArgumentBuilder()
        .add_text("Firstname: ")
        .add_field(aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_MERGE_FIELD).add_argument("firstname")))
field_builder.add_argument(
    aw.fields.FieldArgumentBuilder()
        .add_text("Lastname: ")
        .add_field(aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_MERGE_FIELD).add_argument("lastname")))

# Insert IF field in exact location            
field = field_builder.build_and_insert(doc.first_section.body.first_paragraph)
field.update()

doc.save(ARTIFACTS_DIR + "Field.insert_field_using_field_builder.docx")

使用 DOM 插入字段

您还可以使用 Aspose.Words Document Object Model (DOM) 插入各种类型的字段。在本节中，我们将看一些示例。

使用 DOM 将合并字段插入到文档中

Word文档中的MERGEFIELD字段可以用FieldMergeField类来表示。您可以使用 FieldMergeField 类执行以下操作：

• 指定合并字段的名称
• 指定合并字段的格式
• 指定合并字段的字段分隔符和字段结尾之间的文本
• 如果字段不为空，则指定要在合并字段后插入的文本
• 如果字段不为空，则指定要在合并字段之前插入的文本

以下代码示例演示如何使用 DOM 将 Merge 字段添加到文档中的段落：

# 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)

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()
builder.move_to(para)

# We want to insert a merge field like this:
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" 
field = builder.insert_field(aw.fields.FieldType.FIELD_MERGE_FIELD, False).as_field_merge_field()

#  " MERGEFIELD Test1" 
field.field_name = "Test1"
#  " MERGEFIELD Test1 \\b Test2" 
field.text_before = "Test2"
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 
field.text_after = "Test3"
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" 
field.is_mapped = True
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" 
field.is_vertical_formatting = True

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_merge_field_using_dom.docx")

使用 DOM 将 Mail Merge ADDRESSBLOCK 字段插入文档中

ADDRESSBLOCK字段用于在Word文档中插入mail merge地址块。 Word文档中的ADDRESSBLOCK字段可以用FieldAddressBlock类来表示。您可以使用 FieldAddressBlock 类执行以下操作：

• 指定字段中是否包含国家/地区名称
• 指定是否根据 POST*CODE 定义的收件人国家/地区来格式化地址（Universal Postal Union 2006）
• 指定排除的国家/地区名称
• 指定姓名和地址格式
• 指定用于格式化地址的语言ID

以下代码示例演示如何使用 DOM 将 Mail Merge ADDRESSBLOCK 字段添加到文档中的段落：

# 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)

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()
builder.move_to(para)

# We want to insert a mail merge address block like this:
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" 
field = builder.insert_field(aw.fields.FieldType.FIELD_ADDRESS_BLOCK, False).as_field_address_block()

#  ADDRESSBLOCK \\c 1" 
field.include_country_or_region_name = "1"
#  ADDRESSBLOCK \\c 1 \\d" 
field.format_address_on_country_or_region = True
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 
field.excluded_country_or_region_name = "Test2"
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 
field.name_and_address_format = "Test3"
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" 
field.language_id = "Test 4"

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_mail_merge_address_block_field_using_dom.docx")

在不使用 DocumentBuilder 的情况下将 ADVANCE 字段插入到文档中

ADVANCE 字段用于将行内的后续文本向左、向右、向上或向下偏移。 Word文档中的ADVANCE字段可以用FieldAdvance类来表示。您可以使用 FieldAdvance 类执行以下操作：

• 指定字段后面的文本应从页面顶部边缘垂直移动的点数
• 指定字段后面的文本应从列、框架或文本框的左边缘水平移动的点数
• 指定字段后面的文本应向左、向右、向上或向下移动的点数

以下代码示例演示如何使用 DOM 将 ADVANCE 字段添加到文档中的段落。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an Advance field like this:
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 
field = para.append_field(aw.fields.FieldType.FIELD_ADVANCE, False).as_field_advance()
    
#  ADVANCE \\d 10 " 
field.down_offset = "10"
#  ADVANCE \\d 10 \\l 10 
field.left_offset = "10"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 
field.right_offset = "-3.3"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 
field.up_offset = "0"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 
field.horizontal_position = "100"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 
field.vertical_position = "100"

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_advance_field_with_out_document_builder.docx")

在不使用 DocumentBuilder 的情况下将 ASK 字段插入到文档中

ASK 字段用于提示用户输入要分配给 Word 文档中的书签的文本。 Word文档中的ASK字段可以用FieldAsk类来表示。您可以使用 FieldAsk 类执行以下操作：

• 指定书签的名称
• 指定默认用户响应（提示窗口中包含的初始值）
• 指定每个 Mail Merge 操作是否应接收一次用户响应
• 指定提示文本（提示窗口的标题）

以下代码示例演示如何使用 DOM 将 ASK 字段添加到文档中的段落：

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an Ask field like this:
#  ASK \"Test 1\" Test2 \\d Test3 \\o 
field = para.append_field(aw.fields.FieldType.FIELD_ASK, False).as_field_ask()

#  ASK \"Test 1\" " 
field.bookmark_name = "Test 1"
#  ASK \"Test 1\" Test2 
field.prompt_text = "Test2"
#  ASK \"Test 1\" Test2 \\d Test3 
field.default_response = "Test3"
#  ASK \"Test 1\" Test2 \\d Test3 \\o 
field.prompt_once_on_mail_merge = True

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_ask_field_with_out_document_builder.docx")

在不使用 DocumentBuilder 的情况下将 AUTHOR 字段插入到文档中

AUTHOR 字段用于指定 Document 属性中文档作者的姓名。 Word文档中的AUTHOR字段可以用FieldAuthor类来表示。您可以使用 FieldAuthor 类执行以下操作：

• 指定文档作者的姓名

以下代码示例演示如何使用 DOM 将 AUTHOR 字段添加到文档中的段落：

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an AUTHOR field like this:
#  AUTHOR Test1 
field = para.append_field(aw.fields.FieldType.FIELD_AUTHOR, False).as_field_author()
field.author_name = "Test1" #  AUTHOR Test1 

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_author_field.docx")

在不使用 DocumentBuilder 的情况下将 INCLUDETEXT 字段插入到文档中

INCLUDETEXT 字段插入字段代码中指定的文档中包含的文本和图形。您可以插入整个文档或书签引用的文档的一部分。 Word文档中的该字段由INCLUDETEXT表示。您可以使用 FieldIncludeText 类执行以下操作：

• 指定所包含文档的书签名称
• 指定文档的位置

以下代码示例演示如何使用 DOM 将 INCLUDETEXT 字段添加到文档中的段落：

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

para = aw.Paragraph(doc)

# We want to insert an INCLUDETEXT field like this:
#  INCLUDETEXT  "file path" 
fieldIncludeText = para.append_field(aw.fields.FieldType.FIELD_INCLUDE_TEXT, False).as_field_include_text()
fieldIncludeText.bookmark_name = "bookmark"
fieldIncludeText.source_full_name = docs_base.my_dir + "IncludeText.docx"

doc.first_section.body.append_child(para)

fieldIncludeText.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_include_field_without_document_builder.docx")

在不使用 DocumentBuilder 的情况下将 TOA 字段插入到文档中

TOA（权威表）字段构建并插入权威表。 TOA 字段收集由 TA（权限表条目）字段标记的条目。当您在 References 选项卡上的 权限表 组中单击"插入权限表"时，Microsoft Office Word 会插入 TOA 字段。当您查看文档中的 TOA 字段时，语法如下所示：

{ TOA [Switches ] }

您可以使用 FieldToa 类对 TOA 字段执行操作。

以下代码示例演示如何使用 DOM 将 TOA 字段添加到文档中的段落：

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

# We want to insert TA and TOA fields like this:
#  TA  \c 1 \l "Value 0" 
#  TOA  \c 1 
fieldTA = para.append_field(aw.fields.FieldType.FIELD_TOAENTRY, False).as_field_ta()
fieldTA.entry_category = "1"
fieldTA.long_citation = "Value 0"

doc.first_section.body.append_child(para)

para = aw.Paragraph(doc)

fieldToa = para.append_field(aw.fields.FieldType.FIELD_TOA, False).as_field_toa()
fieldToa.entry_category = "1"
doc.first_section.body.append_child(para)

fieldToa.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_toa_field_without_document_builder.docx")