查找和替换

查找和替换

Aspose.Words FOSS for .NET 提供基于正则表达式的查找和替换，使用 Range.Replace() 实现，可通过 FindReplaceOptions 配置，并且在高级场景下，可使用来自 Aspose.Words.Replacing 命名空间的自定义 IReplacingCallback 实现。

基本查找和替换

Range.Replace(pattern, replacement) 在范围内执行基于正则表达式的搜索替换——当在 Document.Range 上调用时，范围为整个文档。Replace(pattern, replacement, options) 重载接受一个 FindReplaceOptions 对象以进行更精细的控制：MatchCase 和 FindWholeWordsOnly 调整匹配行为，Direction（一个 FindReplaceDirection 值，Forward 或 Backward）控制搜索方向，ApplyFont / ApplyParagraphFormat 使替换能够携带新的格式，而不仅仅是新文本。

格式感知和结构选项

FindReplaceOptions 包含多个标志，用于决定匹配可以跨越或忽略哪些文档结构：IgnoreDeleted 和 IgnoreInserted 控制是否将修订痕迹内容纳入匹配，IgnoreFields 和 IgnoreFieldCodes 控制是否搜索字段结果文本和字段代码，IgnoreFootnotes 排除脚注/尾注内容，IgnoreStructuredDocumentTags 和 IgnoreShapes 分别排除内容控件和形状文本。UseSubstitutions 在替换字符串中启用正则表达式替换语法（如 $1）。LegacyMode 和 UseLegacyOrder 保留较旧的匹配行为，以兼容由早期逻辑处理的文档。

使用 IReplacingCallback 的自定义替换逻辑

对于无法用固定替换字符串表达的替换逻辑，实现 IReplacingCallback 及其唯一的 Replacing(args) 方法，然后将实现分配给 FindReplaceOptions.ReplacingCallback（或直接传递给 FindReplaceOptions(replacingCallback) 构造函数）。回调函数会为每个匹配接收一个 ReplacingArgs 对象，提供 Match（底层正则表达式匹配），MatchNode / MatchEndNode（包含匹配的文档节点），MatchOffset，以及一个可设置的 Replacement 字符串。从回调返回 ReplaceAction 值——Replace、Skip或Stop——可控制该匹配是被替换、保持不变，还是终止整个查找/替换操作。

提示与最佳实践

• 在 Document.Range 上调用 Replace() 进行全文档替换，或在更小的 Range（例如单个章节的范围）上调用，以限定操作范围。
• 设置 FindWholeWordsOnly = true 以避免将搜索词匹配为更长单词的子串。
• 当您希望替换作用于显示的字段结果，而不是底层字段指令文本时，使用 IgnoreFieldCodes = true。
• 如果替换文本依赖于匹配上下文（周围节点、格式或位置），而不是固定字符串，请优先使用 IReplacingCallback 而非后处理。
• 在满足条件后，从回调返回 ReplaceAction.Stop 可提前结束查找/替换操作，而无需处理剩余的每个匹配。

常见问题

FAQ

Range.Replace() 支持正则表达式吗？

是的 — pattern 参数是正则表达式，用于匹配范围的文本。

如何仅在特定章节内替换文本，而不是整个文档？

对该章节的 Range 调用 Replace()，而不是 Document.Range。

如何让替换文本依赖于匹配的内容？

实现 IReplacingCallback，从 ReplacingArgs 读取匹配细节，将 ReplacingArgs.Replacement 设置为计算得到的文本，并返回 ReplaceAction.Replace。

能否在文档中向后搜索进行查找/替换？

是 — 将 FindReplaceOptions.Direction 设置为 FindReplaceDirection.Backward。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation