插入字段

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

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

使用DocumentBuilder将字段插入文档

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

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

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"MERGEFIELD MyFieldName \\* MERGEFORMAT");
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertField.docx");

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

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a few page breaks (just for testing)
for (int i = 0; i < 5; i++)
{
builder->InsertBreak(BreakType::PageBreak);
}
// Move the DocumentBuilder cursor into the primary footer.
builder->MoveToHeaderFooter(HeaderFooterType::FooterPrimary);
// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
System::SharedPtr<Field> field = builder->InsertField(u"IF ");
builder->MoveTo(field->get_Separator());
builder->InsertField(u"PAGE");
builder->Write(u" <> ");
builder->InsertField(u"NUMPAGES");
builder->Write(u" \"See Next Page\" \"Last Page\" ");
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertNestedFields.docx");

在字段级别指定区域设置

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

下面的代码示例演示如何使用此选项:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto builder = MakeObject<DocumentBuilder>();
SharedPtr<Field> field = builder->InsertField(FieldType::FieldDate, true);
field->set_LocaleId(1049);
builder->get_Document()->Save(ArtifactsDir + u"WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

插入无类型/空字段

如果您想像Microsoft Word允许的那样插入无类型/空字段({}),则可以将InsertField方法与FieldType.FieldNone参数一起使用。 要将字段插入Word文档,您可以按"Ctrl+F9"组合键。

下面的代码示例演示如何将空字段插入到文档中:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto field = System::DynamicCast<FieldUnknown>(builder->InsertField(FieldType::FieldNone, false));
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertFieldNone.docx");

使用FieldBuilder将字段插入文档

在Aspose.Words中插入字段的替代方法是FieldBuilder类。 它提供了流畅的接口来指定字段开关和参数值作为文本,节点甚至嵌套字段。

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

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto firstName = MakeObject<FieldBuilder>(FieldType::FieldMergeField);
firstName->AddArgument("firstname");
auto lastName = MakeObject<FieldBuilder>(FieldType::FieldMergeField);
lastName->AddArgument("lastname");
auto firstnameArgumentBuilder = MakeObject<FieldArgumentBuilder>();
firstnameArgumentBuilder->AddText(u"Firstname: ");
firstnameArgumentBuilder->AddField(firstName);
auto lastnameArgumentBuilder = MakeObject<FieldArgumentBuilder>();
lastnameArgumentBuilder->AddText(u"Lastname: ");
lastnameArgumentBuilder->AddField(lastName);
// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
auto fieldBuilder = MakeObject<FieldBuilder>(FieldType::FieldIf);
fieldBuilder->AddArgument(u"left expression");
fieldBuilder->AddArgument(u"=");
fieldBuilder->AddArgument(u"right expression");
fieldBuilder->AddArgument(firstnameArgumentBuilder);
fieldBuilder->AddArgument(lastnameArgumentBuilder);
auto field = fieldBuilder->BuildAndInsert(doc->get_FirstSection()->get_Body()->AppendParagraph(String::Empty));
field->Update();
doc->Save(ArtifactsDir + u"Field.InsertFieldUsingFieldBuilder.docx");

使用DOM插入字段

您还可以使用以下方法插入各种类型的字段 Aspose.Words文档对象模型(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-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto para = System::DynamicCast<Paragraph>(doc->GetChildNodes(NodeType::Paragraph, true)->idx_get(0));
builder->MoveTo(para);
// We want to insert a merge field like this:
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
auto field = System::DynamicCast<FieldMergeField>(builder->InsertField(FieldType::FieldMergeField, false));
// { " MERGEFIELD Test1" }
field->set_FieldName(u"Test1");
// { " MERGEFIELD Test1 \\b Test2" }
field->set_TextBefore(u"Test2");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field->set_TextAfter(u"Test3");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" }
field->set_IsMapped(true);
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
field->set_IsVerticalFormatting(true);
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertMergeFieldUsingDOM.docx");

使用DOM将Mail Merge地址块字段插入文档

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

  • 指定是否在字段中包含国家/地区的名称
  • 指定是否按照POST*CODE所定义的收件人的国家/地区设置地址格式(Universal Postal Union2006)
  • 指定排除的国家/地区名称
  • 指定名称和地址格式
  • 指定用于格式化地址的语言ID

下面的代码示例演示如何使用DOM将Mail MergeADDRESSBLOCK字段添加到文档中的段落:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto para = System::DynamicCast<Paragraph>(doc->GetChildNodes(NodeType::Paragraph, true)->idx_get(0));
builder->MoveTo(para);
// We want to insert a mail merge address block like this:
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
auto field = System::DynamicCast<FieldAddressBlock>(builder->InsertField(FieldType::FieldAddressBlock, false));
// { ADDRESSBLOCK \\c 1" }
field->set_IncludeCountryOrRegionName(u"1");
// { ADDRESSBLOCK \\c 1 \\d" }
field->set_FormatAddressOnCountryOrRegion(true);
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field->set_ExcludedCountryOrRegionName(u"Test2");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field->set_NameAndAddressFormat(u"Test3");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field->set_LanguageId(u"Test 4");
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

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

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

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

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

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto para = System::DynamicCast<Paragraph>(doc->GetChildNodes(NodeType::Paragraph, true)->idx_get(0));
// We want to insert an Advance field like this:
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
auto field = System::DynamicCast<FieldAdvance>(para->AppendField(FieldType::FieldAdvance, false));
// { ADVANCE \\d 10 " }
field->set_DownOffset(u"10");
// { ADVANCE \\d 10 \\l 10 }
field->set_LeftOffset(u"10");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field->set_RightOffset(u"-3.3");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field->set_UpOffset(u"0");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field->set_HorizontalPosition(u"100");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field->set_VerticalPosition(u"100");
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.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-C
auto doc = MakeObject<Document>();
auto para = System::DynamicCast<Paragraph>(doc->GetChildNodes(NodeType::Paragraph, true)->idx_get(0));
// We want to insert an Ask field like this:
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
auto field = System::DynamicCast<FieldAsk>(para->AppendField(FieldType::FieldAsk, false));
// { ASK \"Test 1\" " }
field->set_BookmarkName(u"Test 1");
// { ASK \"Test 1\" Test2 }
field->set_PromptText(u"Test2");
// { ASK \"Test 1\" Test2 \\d Test3 }
field->set_DefaultResponse(u"Test3");
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field->set_PromptOnceOnMailMerge(true);
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.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-C
auto doc = MakeObject<Document>();
auto para = System::DynamicCast<Paragraph>(doc->GetChildNodes(NodeType::Paragraph, true)->idx_get(0));
// We want to insert an AUTHOR field like this:
// { AUTHOR Test1 }
auto field = System::DynamicCast<FieldAuthor>(para->AppendField(FieldType::FieldAuthor, false));
// { AUTHOR Test1 }
field->set_AuthorName(u"Test1");
field->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertAuthorField.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-C
auto doc = MakeObject<Document>();
auto para = MakeObject<Paragraph>(doc);
// We want to insert an INCLUDETEXT field like this:
// { INCLUDETEXT "file path" }
auto fieldIncludeText = System::DynamicCast<FieldIncludeText>(para->AppendField(FieldType::FieldIncludeText, false));
fieldIncludeText->set_BookmarkName(u"bookmark");
fieldIncludeText->set_SourceFullName(MyDir + u"IncludeText.docx");
doc->get_FirstSection()->get_Body()->AppendChild(para);
fieldIncludeText->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

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

TOA(Table of Authorities)字段构建并插入权限表。 TOA字段收集由TA(Table of Authorities Entry)字段标记的条目。 当您在References选项卡上的Table of Authorities组中单击Insert Table of Authorities时,Microsoft Office Word将插入TOA字段。 当您查看文档中的TOA字段时,语法如下所示:

{ TOA [Switches ] }

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

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto para = MakeObject<Paragraph>(doc);
// We want to insert TA and TOA fields like this:
// { TA \c 1 \l "Value 0" }
// { TOA \c 1 }
auto fieldTA = System::DynamicCast<FieldTA>(para->AppendField(FieldType::FieldTOAEntry, false));
fieldTA->set_EntryCategory(u"1");
fieldTA->set_LongCitation(u"Value 0");
doc->get_FirstSection()->get_Body()->AppendChild(para);
para = MakeObject<Paragraph>(doc);
auto fieldToa = System::DynamicCast<FieldToa>(para->AppendField(FieldType::FieldTOA, false));
fieldToa->set_EntryCategory(u"1");
doc->get_FirstSection()->get_Body()->AppendChild(para);
fieldToa->Update();
doc->Save(ArtifactsDir + u"WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");
/