处理构建基块

项目
04/07/2023

Word 2007 中引入的构建基块类似于以前版本中的“自动图文集”词条。不过，采用构建基块，在组织条目时可以决定用户使用这些条目的方式。自定义构建基块可帮助用户使用带格式的下拉列表在文档中的任意位置插入丰富内容。如果与内容控件结合使用，使用构建基块还可以快捷方便地开发功能强大的解决方案。

构建基块对象模型包括三个新的对象和四个新的集合。通过这些对象和集合，您可以针对特定需求创建组织结构，并针对特定解决方案修改该结构。下表列出了这些对象和集合。

名称	说明
BuildingBlock	特定构建基块条目。
BuildingBlocks	模板中属于相同类型和类别的构建基块条目的集合。
BuildingBlockEntries	模板中所有构建基块的集合。
BuildingBlockType	构建基块类型。
BuildingBlockTypes	构建基块类型的集合。
类别	构建基块类别。
类别	构建基块类别的集合。

了解构建基块

构建基块按类型和类别组织。构建基块类型由有限数量的 WdBuildingBlockTypes 常量构成。尽管这些常量的数量有限，不过数量并不小。共有 35 种不同的 WdBuildingBlockTypes 常量。这些类型可帮助您定义和组织构建基块，虽然您无法创建其他构建基块类型，但可以为每个类型创建无限数量的类别。

类别由无限数量的字符串构成，您可以定义这些字符串来组织自定义构建基块。构建基块存储在模板中。默认情况下，Word 附带的模板具有“常规”和“内置”等构建基块类别。不过，您可以使用的类别并不限于这些模板中所包括的类别。类别可以是您定义的任意字符串。本主题后面将讲解类型和类别。

由于可以将构建基块组织到类型和类别中，因此构建基块可以非常灵活。例如，可以有一个名为“Title”的构建基块，该构建基块的类型为 wdTypeBibliography ，一个类别为“Book Titles”，另一个名为“Title”的构建基块的类型为 wdTypeBibliography ，类别为“Movie Titles”，然后您可以拥有另一个名为“Title”的构建基块，该构建基块的类型为 wdTypeCustomHeaders ，类别为“Book Titles”，等等。构建基块提供令人难以置信的灵活性可帮助你创建自定义解决方案，而无需编写代码。

不过，构建基块也是可编程的。您可以通过编程方式创建新的构建基块、删除构建基块和管理构建基块。当用户使用 BuildingBlockInsert 事件在文档中插入新的构建基块时，您还可以进行监视。此外，可以将构建基块与内容控件结合使用，以更好地控制用户能插入其文档的构建基块。例如，可以使用构建基块内容控件筛选用户看到的构建基块类型，这表明用户无法在文档中插入文档特定位置不允许的构建基块。下文给出的几个示例说明如何使用构建基块对象以编程方式处理构建基块。

简单任务

以下部分提供一些简单的示例，说明如何使用构建基块对象执行特定任务。对象主题和很多成员主题中还提供了更多的代码示例。

创建自定义构建基块

创建自定义构建基块就像使用 BuildingBlockEntries 集合的 Add 方法一样简单。还可以对 BuildingBlocks 集合使用 Add 方法;但是，如果当前没有指定类型或类别的构建基块，此方法可能会引发运行时错误。如对象表中所述， BuildingBlocks 集合是特定类型和类别的构建基块的集合。 BuildingBlocksEntries 集合包含模板的所有构建基块。因此，以编程方式添加新构建基块的首选方法是使用 BuildingBlockEntries 集合的 Add 方法。

以下代码示例折叠当前选择内容，创建一个范围并为该范围指定文本，然后将所选内容作为自定义构建基块，添加到当前文档附加的模板的构建基块条目集合中。

Sub AddCustomBuildingBlock() 
 
 Dim objTemplate As Template 
 Dim objBB As BuildingBlock 
 Dim objRange As Range 
 
 ' Set the template to store the building block 
 Set objTemplate = ActiveDocument.AttachedTemplate 
 
 ' Collapse the range, set the range, and add the text 
 Selection.Collapse 
 Set objRange = Selection.Range 
 objRange.Text = "Building blocks for the technically challenged" 
 
 ' Add the building block to the template 
 Set objBB = objTemplate.BuildingBlockEntries.Add( _ 
 Name:="Title", _ 
 Type:=wdTypeCustomHeaders, _ 
 Category:="Book Titles", _ 
 Range:=objRange) 
 
End Sub

添加新类别

如前所述，可以添加无限数量的类别。不过， Categories 集合没有 Add 方法。因此，要向集合添加新的类别，需要添加新的构建基块。例如，在以上代码示例中，如果当运行代码时"Book Titles"类别不存在，Word 将在 Categories 集合中添加该类别。

访问现有构建基块

在某个时候，你需要访问你拥有的构建基块之一，无论是自定义构建基块还是内置构建基块之一。您可以使用 BuildingBlockEntries 集合，不过，由于构建基块可以共用相同的名称，因此您需要识别构建基块的类型和类别才能知道要返回的是哪个构建基块。因此，访问现有构建基块的最佳方法是通过 BuildingBlocks 集合。

以下代码示例访问在上一个代码示例中添加的构建基块。

Sub GetExistingBuildingBlock() 
 
 Dim objTemplate As Template 
 Dim objBB As BuildingBlock 
 
 ' Set the template where the building block is stored 
 Set objTemplate = ActiveDocument.AttachedTemplate 
 
 ' Access the building block through the type and category 
 Set objBB = objTemplate.BuildingBlockTypes(wdTypeCustomHeaders) _ 
 .Categories("Book Titles").BuildingBlocks("Title") 
 
End Sub

在文档中插入构建基块

访问构建基块之后，可以使用 BuildingBlock 对象的 Insert 方法将该构建基块插入文档中。以下代码示例在上一个代码示例的基础上进行扩展，添加一行代码以将构建基块插入活动文档中的插入点（或如果选中文本，则替换所选文本）。

注意

使用功能区插入构建基块时，Word 会自动确定有关构建基块的某些内容，例如插入位置;但是，通过对象模型插入构建基块时，不会自动发生这种内置智能。例如，使用功能区插入标头构建基块时，Word 会自动确定替换现有标头。使用对象模型插入同一标头构建基块时，需要显式指定构建基块文本的放置位置。

Sub InsertExistingBuildingBlock() 
 
 Dim objTemplate As Template 
 Dim objBB As BuildingBlock 
 
 ' Set the template where the building block is stored 
 Set objTemplate = ActiveDocument.AttachedTemplate 
 
 ' Access the building block through the type and category 
 Set objBB = objTemplate.BuildingBlockTypes(wdTypeCustomHeaders) _ 
 .Categories("Book Titles").BuildingBlocks("Title") 
 
 ' Insert the building block into the document replacing any selected text 
 objBB.Insert Selection.Range 
 
End Sub

筛选内容控件中的构建基块列表

如果将构建基块与内容控件结合使用，则可以筛选用户能访问的构建基块。要进行此操作，应使用内容控件和事件。当用户进入内容控件时，将触发 Document 对象的 ContentControlOnEnter 事件。此事件有一个针对活动内容控件的参数。您可以决定该内容控件是否为构建基块内容控件。如果是，则使用 BuildingBlockType 属性和 BuildingBlockCategory 属性确定使用什么类型和类别来筛选可用于该内容控件的构建基块列表。这将指定在内容控件标题的下拉列表中显示哪些构建基块。

以下代码示例假定文档中至少有一个内容控件。如果内容控件为构建基块内容控件，则该内容控件标题的构建基块列表中所显示的构建基块列表只包括那些使用本主题前面所显示的 AddCustomBuildingBlock 子例程添加的构建基块。有关内容控件的详细信息，请参阅使用内容控件。

Private Sub Document_ContentControlOnEnter(ByVal ContentControl As ContentControl) 
 Dim objCC As ContentControl 
 
 Set objCC = ContentControl 
 
 If objCC.Type = wdContentControlBuildingBlockGallery Then 
 objCC.BuildingBlockType = wdTypeCustomHeaders 
 objCC.BuildingBlockCategory = "Book Titles" 
 End If 
End Sub

支持和反馈

有关于 Office VBA 或本文档的疑问或反馈？请参阅 Office VBA 支持和反馈，获取有关如何接收支持和提供反馈的指南。