使用字段
概述
一个 Word 字段 – DATE, IF, DATABASE, REF,以及数十个其他字段 – 在以下中表示 Aspose.Words FOSS 用于 .NET 由 Field 类及其子类,全部位于 Aspose.Words.Fields 命名空间。此页面涵盖核心字段引擎: Field 对象模型本身、字段的收集与更新方式,以及回调接口,使您能够在字段更新期间插入自定义数据和行为。特定的字段族——超链接和交叉引用、日期/时间字段、邮件合并字段、索引和目录字段——各自都有专门的开发者指南页面。
字段对象模型
文档中的每个字段都是一个 Field 实例,由三个标记节点 —— FieldStart、Separator、FieldEnd —— 组成,这些节点以 Field.Start、Field.Separator、Field.End 属性公开。Field.Type 确定字段表示的 FieldType,Field.Result 和 Field.DisplayResult 显示上一次计算的值,Field.Format 保存附加在字段代码上的任何开关(例如数字或日期时间格式字符串)。Field.IsLocked 和 Field.IsDirty 报告字段的锁定和过时状态。调用 Field.GetFieldCode() 读取原始字段代码文本,调用 Field.Update() 重新计算结果,调用 Field.Unlink() 将字段替换为静态文本,调用 Field.Remove() 完全删除该字段。
在文档中访问和更新字段
Document.Range.Fields 返回一个 FieldCollection —— 包含该范围内的字段,并提供 Count、Remove()、RemoveAt()、Clear() 用于批量删除。Range.UpdateFields() 重新计算该范围内的每个字段,Range.UnlinkFields() 将该范围内的每个字段转换为静态文本,Range.NormalizeFieldTypes() 在手动编辑后将字段的存储类型代码与实际字段代码对齐。DocumentBuilder.InsertField() 在光标处插入新字段,提供的重载要么立即更新新字段的结果,要么留待后续的 Range.UpdateFields() 过程。
字段更新选项与文化
Document.FieldOptions 是一个 FieldOptions 实例,用于管理整个文档字段在更新时的行为:CurrentUser 提供身份字段使用的 UserInformation,DefaultDocumentAuthor 为作者相关结果提供种子,LegacyNumberFormat 和 UseInvariantCultureNumberFormat 控制数字格式,PreProcessCulture 和 FieldUpdateCultureSource(配合 IFieldUpdateCultureProvider 回调)决定在更新期间哪个文化支配日期和数字格式。TemplateName、FileName 和 BuiltInTemplatesPaths 提供模板和文件名感知字段读取的值。
跟踪和自定义字段更新
在 FieldOptions 上实现 IFieldUpdatingCallback(FieldUpdating 和 FieldUpdated),以在每次字段重新计算前后立即运行代码——这对审计批处理作业中哪些字段发生了变化很有帮助。实现 IFieldUpdatingProgressCallback(Notify)以跟踪大型文档的整体进度;它接收一个包含 TotalFieldsCount、UpdatedFieldsCount 和 UpdateCompleted 的 FieldUpdatingProgressArgs。若要更改字段的数值或通用结果呈现为文本的方式,实现 IFieldResultFormatter(Format(value, format) 和 FormatNumeric(value, format))并将其分配给 FieldOptions.ResultFormatter。
向字段提供外部数据
DATABASE 字段通过 IFieldDatabaseProvider.GetQueryResult() 读取其行,该方法返回一个由 FieldDatabaseDataRow(Values)实例构建的 FieldDatabaseDataTable(ColumnNames、Rows)——将你的实现分配给 FieldOptions.FieldDatabaseProvider。诸如 IF 的比较字段通过 IComparisonExpressionEvaluator.Evaluate() 评估其条件,该方法接收一个包含 LeftExpression、ComparisonOperator、RightExpression 的 ComparisonExpression 并返回一个 ComparisonEvaluationResult(Result、ErrorMessage);将自定义评估器分配给 FieldOptions.ComparisonExpressionEvaluator 以覆盖默认的比较逻辑。通常在更新期间提示用户输入的字段——例如 ASK 和 FILLIN——在分配给 FieldOptions.UserPromptRespondent 时会调用 IFieldUserPromptRespondent.Respond(),从而避免无人值守的更新因交互式输入而阻塞。
字段的用户和文档身份
UserInformation(Name、Initials、Address 和静态的 UserInformation.DefaultUser)提供作者和用户名称相关字段读取的身份信息。在更新依赖文档作者或用户身份的字段之前,将实例分配给 Document.FieldOptions.CurrentUser。
提示与最佳实践
- Aspose.Words FOSS 不会像 Word 那样在加载或保存时自动重新计算字段——在任何需要在字段结果中体现的程序化编辑之后,需要显式调用
Range.UpdateFields()(单个字段可调用Field.Update())。 FieldStart、Separator和FieldEnd是文档树中的真实节点;请通过Field.Remove()或Field.Unlink()删除字段,而不是直接删除标记节点,否则字段结构可能会变得不一致。- 结果依赖页面布局的字段——
PAGE、NUMPAGES以及目录页码条目——会求值为占位符0,因为此版本不包含页面布局/渲染引擎。 - 如果需要精确记录或审计哪些字段已更改,请在对大型或不熟悉的文档运行
Range.UpdateFields()之前注册IFieldUpdatingCallback。 - 在无人值守的流水线中更新文档之前,设置
FieldOptions.UserPromptRespondent(或在各个提示驱动的字段类上提供DefaultResponse值),以防止ASK/FILLIN字段因等待交互输入而卡住。
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
| 编辑文档后,字段结果已过期 | Aspose.Words FOSS 不会在加载或保存时自动更新字段 | 显式调用 Range.UpdateFields() 或 Field.Update() |
PAGE、NUMPAGES 或 TOC 页码显示 0 | 页面布局/渲染不属于此版本 | 预期行为 – 使用商业版 Aspose.Words 用于 .NET 如果您需要计算的页码 |
DATABASE 字段未产生任何行 | 未将 IFieldDatabaseProvider 分配给 FieldOptions.FieldDatabaseProvider | 实现 IFieldDatabaseProvider 并在调用 Range.UpdateFields() 前分配它 |
| 批量字段更新似乎卡住 | 提示驱动字段(ASK,FILLIN)未分配 IFieldUserPromptRespondent | 在字段实例上分配 FieldOptions.UserPromptRespondent,或设置 DefaultResponse |
FAQ
Aspose.Words FOSS 是否会评估每一种 Word 字段类型?
Field 对象模型表示每个 FieldType 值并更新其中大多数,但其结果取决于页面布局的字段——例如 PAGE 和 NUMPAGES——会评估为占位符 0,因为此版本不包含布局/渲染引擎。
如何在以编程方式编辑文档后重新评估字段?
对覆盖已编辑内容的范围调用 Range.UpdateFields(),或使用 Document.Range.UpdateFields() 来更新文档中的所有字段。
我能将字段转换为普通的静态文本吗?
是的——Field.Unlink() 将字段替换为其最近计算的结果作为普通文本,并移除底层的字段代码。
如何彻底删除字段,包括其结果?
调用 Field.Remove()。它会连同字段代码和结果内容一起删除 FieldStart、Separator 和 FieldEnd 节点。
如何向 DATABASE 字段提供自定义数据?
实现 IFieldDatabaseProvider 并将其分配给 Document.FieldOptions.FieldDatabaseProvider。您的 GetQueryResult() 实现返回一个由 FieldDatabaseDataRow 实例构建的 FieldDatabaseDataTable。
API Reference 摘要
| 类 / 接口 | 描述 |
|---|---|
Field | Word 字段的基类;GetFieldCode(),Update(),Unlink(),Remove() |
FieldCollection | 通过 Range.Fields 获取范围内的字段;Count,Remove(),Clear() |
FieldType | 枚举,用于标识 Field 实例所代表的 Word 字段 |
FieldOptions | 通过 Document.FieldOptions 进行文档范围的字段更新配置 |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated 钩子环绕每个字段更新 |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | 批量字段更新的进度报告 |
IFieldResultFormatter | 字段计算结果的自定义格式化 |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | 用于 DATABASE 字段的外部数据源 |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | 比较式字段表达式的自定义评估 |
IFieldUserPromptRespondent | 在无人值守更新中为提示驱动的字段提供响应 |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | 字段更新期间的区域设置选择 |
UserInformation | 作者/用户身份(Name, Initials, Address)由身份字段读取 |