使用字段

概述

一个 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 摘要

类 / 接口描述
FieldWord 字段的基类;GetFieldCode(),Update(),Unlink(),Remove()
FieldCollection通过 Range.Fields 获取范围内的字段;Count,Remove(),Clear()
FieldType枚举,用于标识 Field 实例所代表的 Word 字段
FieldOptions通过 Document.FieldOptions 进行文档范围的字段更新配置
IFieldUpdatingCallbackFieldUpdating / FieldUpdated 钩子环绕每个字段更新
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs批量字段更新的进度报告
IFieldResultFormatter字段计算结果的自定义格式化
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow用于 DATABASE 字段的外部数据源
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult比较式字段表达式的自定义评估
IFieldUserPromptRespondent在无人值守更新中为提示驱动的字段提供响应
IFieldUpdateCultureProvider / FieldUpdateCultureSource字段更新期间的区域设置选择
UserInformation作者/用户身份(Name, Initials, Address)由身份字段读取

另请参阅

 中文