使用 FieldBuilder 构建字段

使用 FieldBuilder 构建字段

本指南展示了如何在 Aspose.Words FOSS 中为 .NET 从头构建 Word 字段，使用 FieldBuilder and FieldArgumentBuilder, 而不是处理文档中已存在的字段。若要读取、更新或删除已有字段，请参阅 使用字段 指南。

使用 FieldBuilder 创建字段

FieldBuilder 从字段代码标记——参数和开关——构建字段。使用 new FieldBuilder(fieldType) 构造一个，并传入你想构建的字段的 FieldType。使用重载的 AddArgument(argument) 方法添加参数，该方法接受 string、int、double、一个嵌套的 FieldBuilder 或 FieldArgumentBuilder。使用重载的 AddSwitch(switchName)、AddSwitch(switchName, switchArgument)（字符串）或 AddSwitch(switchName, switchArgument)（int/double）方法添加开关。

插入已构建的字段

当 FieldBuilder 完成参数和开关的设置后，调用 BuildAndInsert(refNode) 将其插入文档——一种重载接受一个 Inline 节点并在其前插入字段，另一种接受一个 Paragraph 并在该段落末尾插入字段。

使用 FieldArgumentBuilder 组合复杂参数

FieldArgumentBuilder 构建一个由字段、节点和纯文本组成的复杂字段参数，适用于单个参数需要超过普通字符串的情况。使用 new FieldArgumentBuilder() 创建一个，然后调用 AddText(text) 添加纯文本，调用 AddNode(node) 添加一个 Inline 节点，或使用 AddField(fieldBuilder) 在参数中嵌套另一个字段（使用其自己的 FieldBuilder 构建）。将完成的 FieldArgumentBuilder 传递给 FieldBuilder.AddArgument(argument)，以将其用作外部字段的一个参数。

技巧与最佳实践

• 在构建未由专用字段类（例如 FieldDate 或 FieldSymbol）支持的字段类型时，或在从数据程序化生成字段代码而非手动编写时，使用 FieldBuilder。
• 在简单情况下，可使用 FieldBuilder.AddArgument(FieldBuilder) 将子字段嵌入外部字段的参数中；当参数不仅仅是单个字段，而是由文本、节点和嵌套字段混合组成时，则使用 FieldArgumentBuilder 构建混合参数。
• 选择与字段放置位置相匹配的 BuildAndInsert(refNode) 重载——在特定的 Inline 节点之前，或在 Paragraph 的末尾。
• 在 BuildAndInsert 之后，将结果视为树中的其他字段——例如，如果字段类型需要显式重新计算，则对其调用 Update()。

常见问题

FAQ

我何时应该使用 FieldBuilder 而不是插入预先形成的字段代码？

当您需要在以编程方式构造字段时对字段的参数和开关进行显式控制，而不是插入预先形成的字段代码字符串时，请使用 FieldBuilder。

我该如何向字段添加多个参数？

对每个参数调用一次 AddArgument ——它被重载用于 string、int、double、嵌套的 FieldBuilder 和 FieldArgumentBuilder。

我能构建一个参数中包含文本和另一个字段混合的字段吗？

可以——使用 FieldArgumentBuilder，根据需要调用 AddText、AddNode 和 AddField，然后将其传递给 FieldBuilder.AddArgument。

我该如何将构建好的字段实际放入文档中？

调用 BuildAndInsert(refNode)，传入 Inline 节点（在其前插入）或 Paragraph（在其末尾插入）。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation