构建块
构建块
本指南展示了如何读取和修改存储在文档词汇表文档中的可重用内容构建块，使用 Aspose.Words FOSS 为 .NET。该库通过 Document.GlossaryDocument 和 BuildingBlock/BuildingBlockCollection 对象模型，公开 AutoText 条目、封面页、页眉、页脚以及类似的预定义内容。
词汇表文档
每个 Document 都携带一个 GlossaryDocument —— 可通过 Document.GlossaryDocument 访问 —— 它本身是一个持有构建块的 DocumentBase 子类。它的 BuildingBlocks 属性返回一个 BuildingBlockCollection，并且 FirstBuildingBlock/LastBuildingBlock 提供对列表两端的快速访问。使用 GetBuildingBlock(gallery, category, name) 查找特定的构建块，可匹配其 BuildingBlockGallery、类别字符串和名称。
构建块结构
BuildingBlock 是一个 CompositeNode，因此它拥有自己的内容树 —— Sections（一个 SectionCollection），FirstSection，以及 LastSection —— 与 Document 持有章节的方式相同。它的元数据属性用于标识和分类：Name、Guid、Description、Category、Gallery（一个 BuildingBlockGallery —— AutoText、CoverPage、Headers、Footers、Tables、Watermarks，以及数十个预定义库），Type（一个 BuildingBlockType），以及 Behavior（一个由 Content、Paragraph 或 Page 组成的 BuildingBlockBehavior），用于控制其内容在插入时如何合并到文档中。
管理构建块集合
BuildingBlockCollection 支持完整的集合编辑：Add(node)、Insert(index, node)、Remove(node)、RemoveAt(index)、Clear()、Contains(node) 和 IndexOf(node)，以及用于读取的 ToArray() 和 GetEnumerator()。由于它是一个 NodeCollection，构建块可以使用与文档树其他部分相同的节点 API 来创建、克隆和移动。
占位文本构建块
结构化文档标签可以将构建块作为其占位内容引用：StructuredDocumentTag.Placeholder 和 StructuredDocumentTagRangeStart.Placeholder 都会在标签为空时返回所示的 BuildingBlock，通过共享的 IStructuredDocumentTag.Placeholder 属性。
技巧与最佳实践
- 仔细匹配
GetBuildingBlock(gallery, category, name)的三个参数——相同的名称可能出现在不同的库或类别中。 - 使用
BuildingBlockGallery来过滤您正在寻找的可重用内容类型（AutoText、CoverPage、Tables、Watermarks等），而不是仅凭名称扫描每个构建块。 BuildingBlockBehavior决定插入的内容如何与周围文档合并（Content、Paragraph或Page）——在假设构建块会按预期插入之前，请先检查它。- 由于
BuildingBlock是一个CompositeNode，在构建或编辑其内容时应将其视为其他节点子树——AppendChild、InsertAfter以及类似的节点方法均适用。
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
GetBuildingBlock() 返回空值 | 图库、类别或名称与现有构建块不完全匹配 | 枚举 GlossaryDocument.BuildingBlocks 以找到精确的 Gallery/Category/Name 组合 |
| 插入的构建块内容意外合并 | Behavior (Content/Paragraph/Page) 未计入 | 在插入之前检查 BuildingBlock.Behavior，以了解它将如何合并 |
| 结构化文档标签占位符未显示预期内容 | Placeholder 指向的 BuildingBlock 与假设的不同 | 阅读 StructuredDocumentTag.Placeholder 以确认实际引用的是哪个构建块 |
FAQ
文档中的构建块存储在哪里？
在文档的 GlossaryDocument 中，可通过 Document.GlossaryDocument 访问，其 BuildingBlocks 属性是一个 BuildingBlockCollection。
我如何查找特定的构建块，例如 AutoText 条目？
调用 GlossaryDocument.GetBuildingBlock(gallery, category, name)，并提供匹配的 BuildingBlockGallery、类别和名称。
我可以以编程方式添加新的构建块吗？
是的 —— BuildingBlockCollection 支持 Add(node) 和 Insert(index, node)，因为它是一个 NodeCollection。
BuildingBlockBehavior 控制什么？
当插入构件块时，其内容如何合并到文档中——作为 Content、整个 Paragraph，或整个 Page。
构件块与结构化文档标签的占位符文本之间有什么关联？
StructuredDocumentTag.Placeholder（以及 StructuredDocumentTagRangeStart.Placeholder）返回 BuildingBlock，该 BuildingBlock 在 SDT 为空时提供占位符内容。
API Reference 摘要
| 类 / 方法 | 描述 |
|---|---|
Document.GlossaryDocument | 文档的 GlossaryDocument，包含所有构建块 |
GlossaryDocument.BuildingBlocks | 每个构件的BuildingBlockCollection |
GlossaryDocument.GetBuildingBlock() | 通过画廊、类别和名称查找构件 |
BuildingBlock | 一个CompositeNode，带有Name、Gallery、Category、Behavior、Type、Sections |
BuildingBlockCollection | Add(), Insert(), Remove(), Clear(), Contains(), IndexOf() |
BuildingBlockGallery / BuildingBlockType / BuildingBlockBehavior | 用于对构建块进行分类的枚举 |
StructuredDocumentTag.Placeholder | 用作 SDT 占位符内容的 BuildingBlock |
