使用文档

使用文档

Aspose.Words FOSS for .NET 将每个 Word 文件表示为以 Document 类为根的内存对象模型，DocumentBuilder 提供了一个高级的基于光标的 API 用于编写内容。本指南涵盖了文档的创建与加载、使用 DocumentBuilder 进行创作、章节/正文结构、遍历节点树、合并文档以及对文档的保护。

创建与加载文档

使用 new Document() 创建一个空白文档，或通过向 Document(fileName) 或 Document(stream) 构造函数传递路径或 Stream 来打开已有文件。接受 LoadOptions 参数的重载允许您控制加载行为，例如为加密文件提供密码。

在从未知或不可信来源加载文件之前，FileFormatUtil.DetectFileFormat(fileName)（或 Stream 重载）会返回一个 FileFormatInfo，描述检测到的 LoadFormat，以及文件是 IsEncrypted、HasDigitalSignature 还是 HasMacros。

使用 DocumentBuilder 进行创作

DocumentBuilder 包装了一个 Document 并公开一个光标，您可以在插入内容时在文档中移动该光标。Write(text) 和 Writeln(text) 在光标位置插入文本；InsertParagraph() 开始一个新段落。构建器上的格式属性 — Font、ParagraphFormat、ListFormat、PageSetup — 将应用于随后写入的内容。

使用 MoveToDocumentStart()、MoveToDocumentEnd()、MoveToSection(sectionIndex)、MoveToBookmark(bookmarkName) 或 MoveToParagraph(paragraphIndex, characterIndex) 移动光标。构建器的 CurrentNode、CurrentParagraph 和 CurrentSection 属性报告其在树中的当前位置。

文档结构：章节和正文

一个 Document 包含一个 SectionCollection（Document.Sections，以及 FirstSection / LastSection）；每个 Section 拥有一个 Body，可选的页眉/页脚集合，以及它自己的 PageSetup。Section.AppendContent(sourceSection) 和 PrependContent(sourceSection) 在章节之间复制内容，而 ClearContent() 在不从文档中移除章节的情况下重置章节。

在 Body 中，内容通过 Body.Paragraphs（一种 ParagraphCollection）和 Body.Tables 暴露。Range ——可从 Document、Section、Paragraph 以及其他节点获取——表示树中的连续区域；Range.Text 读取其纯文本，Range.Replace(pattern, replacement) 在该区域执行查找替换。

使用 DocumentVisitor 遍历节点树

文档的每个部分——章节、段落、运行、表格、域、形状、批注、脚注——都是根植于 Document 的复合树中的 Node。若要在不手动递归的情况下处理特定类型的每个节点，需子类化抽象的 DocumentVisitor 并覆盖所需的 Visit*Start / Visit*End 回调，例如 VisitParagraphStart(paragraph) 或 VisitRun(run)，然后调用 document.Accept(visitor)。每个回调可以返回一个 VisitorAction（Continue、SkipThisNode 或 Stop），以控制遍历的进行方式。

克隆、导入和追加内容

Document.Clone() 生成整个文档的深拷贝。要在两个不同的 Document 实例之间移动内容，可在目标文档上调用 ImportNode(srcNode, isImportChildren) 将外部树中的节点导入，或调用 Document.AppendDocument(srcDoc, importFormatMode) 使用选定的 ImportFormatMode（KeepSourceFormatting、UseDestinationStyles 或 KeepDifferentStyles）将一个文档的章节追加到另一个文档。DocumentBuilder.InsertDocument(srcDoc, importFormatMode) 将源文档的内容插入构建器的光标位置，而不是放在目标文档的末尾。

保护文档

Document.Protect(type, password) 根据 ProtectionType 值限制编辑——ReadOnly、AllowOnlyComments、AllowOnlyRevisions、AllowOnlyFormFields 或 NoProtection 可解除保护。Unprotect()（可带密码或不带密码）会恢复编辑。这是 Word 强制的编辑限制，区别于 OoxmlSaveOptions.Password 在保存文件时应用的 OOXML 密码加密。

技巧与最佳实践

• 在构建新内容时首选 DocumentBuilder；当需要对已有树进行精细控制时，可转而直接操作节点（AppendChild、InsertAfter、Clone）。
• 在从不可信或用户提供的来源加载文件之前调用 FileFormatUtil.DetectFileFormat，以便检查 LoadFormat 并提前拒绝不支持或加密的输入。
• 使用 AppendDocument 或 InsertDocument 合并文档时，请有意选择 ImportFormatMode——KeepSourceFormatting 保持源文档的外观，UseDestinationStyles 则匹配目标文档的样式集。
• 当需要一致地处理某种节点类型的每个实例时，使用 DocumentVisitor 子类，而不是手动递归遍历树。
• Document.Protect 是一种编辑限制，而非加密——如果保存的文件本身必须在打开时要求密码，请将其与 OoxmlSaveOptions.Password 结合使用。

常见问题

FAQ

Document.Clone() 和 ImportNode 有什么区别？

Clone() 将整个文档复制到新的 Document 实例中。ImportNode(srcNode, isImportChildren) 将单个节点（以及可选的子节点）从一个文档的树结构带入另一个文档，这是在合并特定内容而非整个文档时使用的方式。

Document(fileName) 能加载哪些文件格式？

Document(fileName) 加载 DOCX、DOCM、DOTX、DOTM、Flat OPC（以及其宏启用和模板变体）、Markdown 和纯文本。旧的文字处理和网页格式不在此版本的加载器中。

我如何找到 DocumentBuilder 当前所在的位置？

在构建器实例上读取 CurrentNode、CurrentParagraph 或 CurrentSection。

Document.Protect 会加密已保存的文件吗？

不—这是 Word 在打开文件时强加的编辑限制。若要仅在打开文件时要求密码，请在保存时设置 OoxmlSaveOptions.Password。

我如何仅读取文档正文中的段落？

使用 Body.Paragraphs 集合，或者对于其他节点类型使用 Body.GetChildNodes(nodeType, isDeep)。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation