使用 LoadOptions 加载文档
使用 LoadOptions 加载文档
本指南展示了如何使用 LoadOptions 类在仅文件路径或流之外控制文档加载。Document 提供了接受 LoadOptions 实例的构造函数重载——Document(fileName, loadOptions) 和 Document(stream, loadOptions)——因此此处描述的所有设置都会在加载时生效，在文档对象返回给您的代码之前。
LoadOptions 类
LoadOptions 承载了 Aspose.Words FOSS 在将文档加载到 Document 对象时所需的设置。它的构造函数包括无参的 LoadOptions()、用于直接打开受密码保护文件的 LoadOptions(password)，以及用于显式指定格式的 LoadOptions(loadFormat, password, baseUri)。除了用于解析相对引用（如链接资源）的 Password 和 BaseUri 外，LoadOptions 公开了针对基于文本格式的 Encoding，用于大文档处理的 TempFolder，用于指定适用的 Word 版本格式约定的 MswVersion，以及用于更细粒度加载行为控制的 UpdateDirtyFields、IgnoreOleData 和 UseSystemLcid。LoadOptions.FontSettings 允许您在加载时提供 FontSettings，而不是仅在文档加载后才配置字体。
特定格式的加载选项
某些格式拥有各自的 LoadOptions 子类，公开针对该格式的特定设置。TxtLoadOptions（用于纯文本）添加了 AutoNumberingDetection、DetectNumberingWithWhitespaces、DetectHyperlinks、DocumentDirection，以及类型为 TxtLeadingSpacesOptions/TxtTrailingSpacesOptions 的独立 LeadingSpacesOptions/TrailingSpacesOptions，用于控制每行前后空白的处理方式。MarkdownLoadOptions 添加了 PreserveEmptyLines、ImportUnderlineFormatting 和 SoftLineBreakCharacter，用于控制 Markdown 的换行约定如何映射到文档段落和运行。两个子类都继承了所有通用的 LoadOptions 属性，因此在 TxtLoadOptions 或 MarkdownLoadOptions 实例上设置的密码或资源加载回调，其行为与基类相同。
资源加载回调
LoadOptions.ResourceLoadingCallback 接受一个 IResourceLoadingCallback 的实现，当加载器解析被加载文档引用的外部资源时会通知它。回调函数收到一个描述被加载资源的 ResourceType 的 ResourceLoadingArgs，并返回一个 ResourceLoadingAction，用以告诉加载器是正常加载资源、跳过还是替换为自定义数据。这是控制或拦截加载期间资源解析的扩展点，独立于所读取的格式。
语言、方向和恢复设置
LoadOptions.LanguagePreferences 是一个 LanguagePreferences 对象，其 DefaultEditingLanguage（一个 EditingLanguage 枚举值）设置 FOSS 在文档未明确指定语言时假定的语言 Aspose.Words；AddEditingLanguage(language) 和 AddEditingLanguages(languages) 用于注册文档可能使用的其他语言。DocumentDirection（也直接在 TxtLoadOptions 上暴露）是一个枚举，包含 LeftToRight、RightToLeft 和 Auto 值，用于在加载时控制文本流向。LoadOptions.RecoveryMode 接受一个 DocumentRecoveryMode 值，用来控制加载器在遇到格式错误或部分损坏的文档时的响应方式。
进度和警告回调
除了资源加载之外，LoadOptions.WarningCallback 和 LoadOptions.ProgressCallback 接受回调实现，前者在加载过程中收到非致命问题的通知，后者收到加载进度的通知——这对于向调用代码呈现可恢复的问题或在不轮询的情况下报告大文档的加载进度非常有用。
提示与最佳实践
- 传入
LoadOptions(password)（或设置LoadOptions.Password），而不是捕获加载异常后再重试——Aspose.Words FOSS 在能够解析文档之前就需要密码。 - 在加载语言元数据缺失或不可靠的文档时设置
LanguagePreferences.DefaultEditingLanguage，以确保后续依赖语言的处理能够以可预测的方式运行。 - 在加载这些格式时，优先使用特定格式的选项类（
TxtLoadOptions，MarkdownLoadOptions）而不是基础LoadOptions，因为特定子类公开了基础类没有的与格式相关的设置。 - 在需要在加载期间而不是文档已在内存中之后重定向、缓存或阻止外部资源解析时，实现
IResourceLoadingCallback。 - 有意为处理来自不可信或第三方来源文档的管道设置
LoadOptions.RecoveryMode，而不是依赖默认的恢复行为。
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
| 加载受密码保护的文档时抛出异常 | 未提供密码，或在加载已经开始后才提供密码 | 将 LoadOptions(password)（或在 LoadOptions 实例上设置 Password）传递给接受 LoadOptions 的 Document 构造函数重载 |
| 加载的文本文件中的前导/尾随空白未按预期处理 | 默认的 TxtLeadingSpacesOptions/TxtTrailingSpacesOptions 行为与源文件的空白约定不匹配 | 显式设置 TxtLoadOptions.LeadingSpacesOptions / TrailingSpacesOptions |
| Markdown 换行未映射到预期的段落结构 | MarkdownLoadOptions.PreserveEmptyLines 或 SoftLineBreakCharacter 与源 Markdown 的约定不匹配 | 在加载之前调整相关的 MarkdownLoadOptions 属性 |
| 外部资源加载未被观察或无法控制 | 在 LoadOptions.ResourceLoadingCallback 上未注册 IResourceLoadingCallback | 实现 IResourceLoadingCallback 并在加载前分配它 |
FAQ
我该如何加载受密码保护的文档？
使用密码构造 LoadOptions —— new LoadOptions(password) —— 或设置 LoadOptions.Password，随后将其传递给 new Document(fileName, loadOptions) 或 new Document(stream, loadOptions)。
我是否需要特定格式的 LoadOptions 子类，还是基础类已经足够？
基础 LoadOptions 类涵盖了每种格式通用的设置（密码、编码、回调）。当需要特定于某种格式的设置时，例如文本文件的空白处理或 Markdown 的换行约定，请使用诸如 TxtLoadOptions 或 MarkdownLoadOptions 之类的格式特定子类。
在加载过程中，我如何拦截或重定向文档引用的资源？
在加载前实现 IResourceLoadingCallback 并将其分配给 LoadOptions.ResourceLoadingCallback。回调会为每个资源接收一个 ResourceLoadingArgs，并返回一个 ResourceLoadingAction，决定加载器的后续行为。
我如何控制 Aspose.Words FOSS 对已加载文档假定的语言？
在加载前将 LoadOptions.LanguagePreferences.DefaultEditingLanguage 设置为 EditingLanguage 值；使用 AddEditingLanguage/AddEditingLanguages 注册文档可能包含的其他语言。
如果加载器遇到格式错误的文档会怎样？
行为由 LoadOptions.RecoveryMode 控制，它是一个 DocumentRecoveryMode 值，用于决定加载器如何响应源文档中的结构性问题。
API Reference 摘要
| 类/方法 | 描述 |
|---|---|
LoadOptions | 控制文档加载方式的基础选项对象 |
Document(fileName, loadOptions) / Document(stream, loadOptions) | 在加载时应用 LoadOptions 的构造函数重载 |
TxtLoadOptions | 针对纯文本文档的加载选项 |
MarkdownLoadOptions | 针对 Markdown 文档的加载选项 |
IResourceLoadingCallback | 在加载期间拦截外部资源解析的回调接口 |
ResourceLoadingArgs / ResourceLoadingAction | 每个资源的事件数据以及返回给加载器的操作 |
LanguagePreferences | 配置加载时默认和额外的编辑语言 |
DocumentDirection | 控制文本流向的枚举（LeftToRight, RightToLeft, Auto） |
DocumentRecoveryMode | 在文档格式错误时控制加载器行为 |
