使用 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()。
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
BuildAndInsert 指向了错误的位置 | 错误地使用了用于预期插入点的重载 | 传入一个 Inline 节点以在其前插入,或传入一个 Paragraph 以在其末尾插入 |
| 字段参数不能同时接受纯文本和节点 | AddArgument 被调用时使用了单个 string/int/double,而不是组合参数 | 使用 FieldArgumentBuilder(AddText、AddNode、AddField)构建混合参数,并将其传递给 AddArgument |
| 在生成的字段代码中未识别开关值 | 在开关实际需要参数时使用了 AddSwitch(switchName) | 使用带有开关的字符串、int 或 double 值的 AddSwitch(switchName, switchArgument) 重载 |
FAQ
我何时应该使用 FieldBuilder 而不是插入预先形成的字段代码?
当您需要在以编程方式构造字段时对字段的参数和开关进行显式控制,而不是插入预先形成的字段代码字符串时,请使用 FieldBuilder。
我该如何向字段添加多个参数?
对每个参数调用一次 AddArgument ——它被重载用于 string、int、double、嵌套的 FieldBuilder 和 FieldArgumentBuilder。
我能构建一个参数中包含文本和另一个字段混合的字段吗?
可以——使用 FieldArgumentBuilder,根据需要调用 AddText、AddNode 和 AddField,然后将其传递给 FieldBuilder.AddArgument。
我该如何将构建好的字段实际放入文档中?
调用 BuildAndInsert(refNode),传入 Inline 节点(在其前插入)或 Paragraph(在其末尾插入)。
API Reference 摘要
| 类/方法 | 描述 |
|---|---|
FieldBuilder | 从字段代码标记(参数和开关)构建字段 |
FieldBuilder(fieldType) | 构造函数接受 FieldType 进行构建 |
FieldBuilder.AddArgument(argument) | 添加参数(string、int、double、FieldBuilder或FieldArgumentBuilder) |
FieldBuilder.AddSwitch(switchName) / AddSwitch(switchName, switchArgument) | 添加一个字段开关,可带值或不带值 |
FieldBuilder.BuildAndInsert(refNode) | 在 Inline 节点之前插入构建的字段,或在 Paragraph 的末尾插入 |
FieldArgumentBuilder | 从文本、节点和嵌套字段构建复杂的字段参数 |
FieldArgumentBuilder.AddText(text) | 向参数添加纯文本 |
FieldArgumentBuilder.AddNode(node) | 向参数添加一个 Inline 节点 |
FieldArgumentBuilder.AddField(fieldBuilder) | 将由 FieldBuilder 构建的字段嵌套到参数中 |