内容控件

更新： 2008 年 7 月

利用内容控件可以设计具有以下功能的文档和模板：

• 一个用户界面 (UI)，其中包含类似于窗体的受控输入。

• 可防止用户编辑文档或模板受保护部分的限制。有关更多信息，请参见使用内容控件保护文档的各个部分。

• 到数据源的数据绑定。有关更多信息，请参见将数据绑定到内容控件。

内容控件概述

内容控件提供了一个同时针对用户输入和打印优化过的 UI。向文档中添加内容控件时，控件由边框、标题和可向用户提供说明的临时文本标识。控件的边框和标题不会出现在文档的打印版本中。

例如，如果想要用户在文档的某个部分中输入日期，您可以向文档中添加日期选择器内容控件。当用户单击该控件时，将出现标准的日期选择器 UI。您还可以设置该控件的属性，以便设置显示的区域日历和指定日期格式。用户选择了日期后，控件的 UI 将隐藏，并且，如果用户打印文档，只有日期会出现。

内容控件还可帮助您执行下列操作：

• 防止用户编辑或删除文档的某些部分。如果文档或模板上有用户应能够读取但不能编辑的信息，或者，如果您希望用户能够编辑但不能删除内容控件，这一点非常有用。

• 将文档或模板的各部分绑定到数据。可以将内容控件绑定到数据库字段、.NET Framework 中的托管对象、存储在文档中的 XML 元素以及其他数据源。

在文档级项目中，您可以在设计时或运行时向文档中添加内容控件。从 Visual Studio 2008 Service Pack 1 (SP1) 开始，可以使用应用程序级外接程序在运行时向任何打开的文档添加内容控件。有关更多信息，请参见如何：向 Word 文档添加内容控件。

说明：
只能在采用 Word 2007 中的 Open XML 格式保存的文档中使用内容控件。不能在采用 Word 97-2003 文档 (.doc) 格式保存的文档中使用内容控件。

内容控件的类型

可使用 Visual Studio Tools for Office 添加到文档的内容控件共有八种不同类型。每种内容控件在 Microsoft.Office.Tools.Word 命名空间中都有对应的类。您也可以使用 ContentControl 类，该类可以表示任何可用的内容控件。

有关演示如何使用每种可用内容控件的演练，请参见演练：使用内容控件创建模板。

构造块库

构造块库使用户能够从“文档构造块”的列表中进行选择以插入文档。文档构造块是创建用来重复使用的一部分内容，例如共用封面页、带格式的表或标题。有关更多信息，请参见 BuildingBlockGalleryContentControl 类。有关构造块的更多信息，请参见 Word 2007 针对开发人员的新功能。

组合框

组合框显示用户可以选择的项列表。与下拉列表不同，组合框允许用户添加自己的项。有关更多信息，请参见 ComboBoxContentControl 类。

日期选择器

日期选择器提供一个用于选择日期的日历 UI。在最终用户单击该控件中的下拉箭头时，日历将会出现。您可以使用区域日历和不同的日期格式。有关更多信息，请参见 DatePickerContentControl 类。

下拉列表

下拉列表显示用户可以选择的项列表。与组合框不同，下拉列表不允许用户添加或编辑项。有关更多信息，请参见 DropDownListContentControl 类。

组

组控件定义用户无法编辑或删除的受保护文档区域。组控件可包含任何文档项，比如文本、表格、图形以及其他内容控件。有关更多信息，请参见 GroupContentControl 类。

图片

图片控件可显示图像。您可以在设计时或运行时指定图像，或者用户可以单击此控件来选择插入到文档中的图像。有关更多信息，请参见 PictureContentControl 类。

多格式文本

多格式文本控件包含文本或其他项，比如表格、图片或其他内容控件。有关更多信息，请参见 RichTextContentControl 类。

纯文本

纯文本控件包含文本。纯文本控件无法包含其他项，比如表格、图片或其他内容控件。此外，纯文本控件中的所有文本都具有相同的格式设置。例如，如果将纯文本控件中某个句子的一个单词设置为斜体，则该控件中的所有文本都将设置为斜体。有关更多信息，请参见 PlainTextContentControl 类。

ContentControl

ContentControl 对象是一种可变控件，它可以表示八种内容控件类型中的任何一种。通过使用 Type 属性，您可以更改 ContentControl 对象，以使其具有类似于其他类型内容控件的行为。例如，如果创建了表示纯文本控件的 ContentControl 对象，则可以在运行时对其进行更改，使之具有类似于组合框的行为。

只能在运行时创建 ContentControl 对象，而不能在设计时创建。有关更多信息，请参见如何：向 Word 文档添加内容控件。

内容控件的公共特性

Visual Studio Tools for Office 中的大部分内容控件都有一组您可用于执行常见任务的成员。下表描述了您可以使用这些成员执行的一些任务。

对于此任务：	执行此操作：
获取或设置控件中显示的文本。	使用 Text 属性。 说明： PictureContentControl 和 ContentControl 类没有此属性。
获取或设置临时文本，在用户编辑控件、用数据源中的数据填充控件，或者控件内容被删除之前，临时文本将显示在控件中。	使用 PlaceholderText 属性。 说明： PictureContentControl 类没有此属性。
获取或设置当用户单击内容控件时显示在该控件边框中的标题。	使用 Title 属性。
在用户编辑控件后从文档中自动移除控件。（控件中的文本将保留在文档中。）	使用 Temporary 属性。
在用户单击内容控件时，或者当光标通过编程方式移入内容控件时运行代码。	处理控件的 Entering 事件。
在用户单击内容控件外部时，或者当光标通过编程方式移出内容控件时运行代码。	处理控件的 Exiting 事件。
在由于重做或撤消操作而将内容控件添加到文档后运行代码。	处理控件的 Added 事件。
在内容控件从文档中删除之前运行代码。	处理控件的 Deleting 事件。

使用内容控件保护文档的各个部分

如果保护文档的某个部分，将会防止用户更改或删除文档该部分中的内容。可通过多种方式用内容控件来保护文档的各个部分。

如果要保护的区域在内容控件内部，您可以使用内容控件的属性来防止用户编辑或删除控件：

• LockContents 属性可防止用户编辑内容。

• LockContentControl 属性可防止用户删除控件。

如果要保护的区域不在内容控件内部，或者，如果要保护包含内容控件和其他类型内容的区域，您可以将整个区域放在 GroupContentControl 中。与其他内容控件不同，GroupContentControl 未提供用户可看到的 UI。它的唯一用途是定义一个用户无法编辑的区域。

说明：
如果创建一个包含嵌入式内容控件的 GroupContentControl，则不会自动保护这些嵌入式内容控件。必须使用每个嵌入式控件的 LockContents 属性来防止用户编辑控件的内容。

有关如何使用内容控件来保护文档各部分的更多信息，请参见如何：使用内容控件保护文档的某些部分。

将数据绑定到内容控件

可以通过将内容控件绑定到数据源而在文档中显示数据。数据源更新后，内容控件将反映更改。您也可以将更改保存回数据源。

内容控件提供了以下数据绑定选项：

• 可以使用与 Windows 窗体相同的数据绑定模型将内容控件绑定到数据库字段或托管对象。

• 可将内容控件绑定到嵌入在文档中的 XML 段（也称为“自定义 XML 部件”）内的元素。

有关将 Visual Studio Tools for Office 解决方案中的宿主控件绑定到数据的概述，请参见将数据绑定到控件。

使用 Windows 窗体数据绑定模型

大多数内容控件都支持 Windows 窗体使用的简单数据绑定模型。简单数据绑定意指将控件绑定到单个数据元素，比如数据表某列中的一个值。有关更多信息，请参见数据绑定和 Windows 窗体。

在文档级项目中，可以使用 Visual Studio 中的“数据源”窗口将数据绑定到内容控件。有关如何向文档中添加数据绑定内容控件的更多信息，请参见如何：用数据库中的数据填充文档和如何：用对象中的数据填充文档。

下表列出了您可在“数据源”窗口中绑定到每种数据类型的内容控件。

在文档级和应用程序级项目中，可以使用内容控件的 DataBindings 属性的 Add 方法以编程方式将此控件绑定到数据源。如果这样做，请将字符串 Text 传入 Add 方法的 propertyName 参数。Text 属性是内容控件的默认数据绑定属性。

内容控件还支持双向数据绑定，在这种绑定中，控件中的更改会更新到数据源中。有关更多信息，请参见如何：使用宿主控件中的数据更新数据源。

说明：
内容控件不支持复杂数据绑定。如果您使用 Windows 窗体数据模型将 DropDownListContentControl 或 ComboBoxContentControl 绑定到数据源，用户在单击控件时将只会看到单一值。如果要将这些控件绑定到一组用户可从中选择的数据值，您可以将这些控件绑定到自定义 XML 部件中的元素。

将内容控件绑定到自定义 XML 部件

可以将某些内容控件绑定到嵌入在文档中的自定义 XML 部件中的元素。有关自定义 XML 部件的更多信息，请参见自定义 XML 部件概述。

若要将某个内容控件绑定到自定义 XML 部件中的元素，请使用该控件的 XMLMapping 属性。下面的代码示例演示如何将 PlainTextContentControl 绑定到已添加到文档的自定义 XML 部件中 Product 节点下的 Price 元素。

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

有关详细演示如何将内容控件绑定到自定义 XML 部件的演练，请参见演练：将内容控件绑定到自定义 XML 部件。

将内容控件绑定到自定义 XML 部件时，会自动启用双向数据绑定。如果用户在控件中编辑文本，对应的 XML 元素会自动更新。同样，如果更改了自定义 XML 部件中的元素值，绑定到 XML 元素的内容控件将显示新数据。

可以将以下类型的内容控件绑定到自定义 XML 部件：

• ComboBoxContentControl

• DatePickerContentControl

• DropDownListContentControl

• PictureContentControl

• PlainTextContentControl

内容控件的数据绑定事件

所有内容控件都提供了一组您可进行处理以执行数据相关任务（比如在更新数据源之前验证控件中的文本是否满足特定条件）的事件。下表列出了与数据绑定相关的内容控件事件。

内容控件的限制

在 Visual Studio Tools for Office 项目中使用内容控件时，请注意以下限制。

设计时行为与运行时行为的差异

Microsoft Office Word 在运行时对内容控件施加的多数限制在设计时都不会实施。在 Visual Studio 中设计文档级解决方案的 UI 时，务必只采用在运行时支持的方式来修改内容控件。

如果在设计时采用控件在运行时不支持的方式来修改内容控件，Visual Studio 设计器将不会向您发出更改不受支持的警报。但是，当您调试或运行项目时，或者，如果保存并稍后重新打开项目，Word 将显示一条错误消息，并请求允许修复文档。当您修复文档时，Word 将从控件中移除所有不支持的内容和格式设置。

例如，Word 不会阻止您在设计时向 PlainTextContentControl 中添加表格。但是，由于 PlainTextContentControl 对象在运行时不能包含表格，因此，在打开文档时，Word 将显示一条错误消息。

同时请注意，许多定义内容控件行为的属性在设计时都没有效果。例如，如果在设计时将内容控件的 LockContents 属性设置为 True，您仍然能够在 Visual Studio 设计器中编辑该控件中的文本。此属性只会在运行时防止用户编辑控件。

事件限制

内容控件未提供当用户更改控件中的文本或其他项时引发的事件。例如，当用户在 DropDownListContentControl 或 ComboBoxContentControl 中选择不同的项时，将不会有引发的事件。

若要确定用户何时编辑内容控件的内容，您可以将控件绑定到自定义 XML 部件，然后处理 StoreUpdating 事件。当用户更改绑定到自定义 XML 部件的控件的内容时，将引发此事件。有关演示如何将内容控件绑定到自定义 XML 部件的演练，请参见演练：将内容控件绑定到自定义 XML 部件。

请参见

任务

如何：向 Word 文档添加内容控件

演练：使用内容控件创建模板

概念

将数据绑定到控件

宿主项和宿主控件的编程限制

其他资源

Word 宿主控件

Office 解决方案中的数据

修订记录