通过

内容控件

内容控件提供了一种设计具有以下功能的文档和模板的方法：

关于内容控件

内容控件提供针对用户输入和打印进行优化的 UI。 向文档添加内容控件时，控件由边框、标题和临时文本标识，可为用户提供说明。 控件的边框和标题不会显示在文档的打印版本中。

例如，如果希望用户在文档的某个部分中输入日期，则可以向文档添加日期选取器内容控件。 当用户单击该控件时，将显示标准日期选取器 UI。 还可以设置控件的属性，以设置显示的区域日历并指定日期格式。 用户选择日期后，控件的 UI 处于隐藏状态，并且仅当用户打印文档时才会显示日期。

内容控件还有助于帮助您完成以下内容：

  • 阻止用户编辑或删除文档的某些部分。 如果你在文档或模板中有用户应能够阅读但不能编辑的信息，或者希望用户能够编辑内容控件但不能删除这些控件，这非常有用。

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

    在文档级项目中，可以在设计时或运行时向文档添加内容控件。 在 VSTO 外接程序项目中，可以在运行时将内容控件添加到任何打开的文档。 有关详细信息，请参阅 “如何：向 Word 文档添加内容控件”。

注释

只能在以 Open XML 格式保存的文档中使用内容控件。 不能在 Word 97-2003 文档（.doc）格式保存的文档中使用内容控件。

内容控件的类型

可以添加到文档的九种不同类型的内容控件。 大多数内容控件在 Microsoft.Office.Tools.Word 命名空间中都有相应的类型。 还可以使用泛型，该泛型 ContentControl可以表示任何可用内容控件。 有关演示如何使用每个可用内容控件的演练，请参阅 演练：使用内容控件创建模板。

构建基块库允许用户从 文档构建基块 列表中进行选择，以插入文档。 文档构建基块是一段内容，该内容已创建多次使用，例如公共封面、格式化表或页眉。 有关详细信息，请参阅类型 BuildingBlockGalleryContentControl 。 有关构建基块的详细信息，请参阅 Word 2007 中面向开发人员的新增功能。

复选框

复选框提供表示二进制状态的 UI：已选中或清除。

与其他类型的内容控件不同，Visual Studio Tools for Office 运行时不提供表示复选框内容控件的特定类型。 换句话说，没有 CheckBoxContentControl 类型。 但是，仍可以通过以编程方式向文档添加泛型 ContentControl 来创建复选框内容控件。 有关详细信息，请参阅 Word 项目中的复选框内容控件。

组合框

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

日期选择器

日期选取器提供了一个日历界面，用于选择日期。 当最终用户单击控件中的下拉箭头时，将显示日历。 可以使用区域日历和不同的日期格式。 有关详细信息，请参阅类型 DatePickerContentControl 。

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

组

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

图片

图片控件显示图像。 可以在设计时或运行时指定图像，或者用户可以单击此控件选择要插入文档中的图像。 有关详细信息，请参阅类型 PictureContentControl 。

富文本

格式文本控件包含文本或其他项，如表格、图片或其他内容控件。 有关详细信息，请参阅类型 RichTextContentControl 。

纯文本

纯文本控件包含文本。 纯文本控件不能包含其他项目，如表格、图片或其他内容控件。 此外，纯文本控件中的所有文本都具有相同的格式。 例如，如果将纯文本控件中某个句子的一个单词斜体化，则控件中的所有文本都会斜体化。 有关详细信息，请参阅类型 PlainTextContentControl 。

泛型内容控件

泛型内容控件是一个 ContentControl 对象，可以表示任何可用的内容控件类型。 可以通过使用Type 属性，将 ContentControl 对象更改为模拟不同类型的内容控件。 例如，如果创建表示 ContentControl 纯文本控件的对象，则可以在运行时对其进行更改，使其行为类似于组合框。

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

内容控件的常见功能

大多数内容控件共享一组可用于执行常见任务的成员。 下表描述了可以使用这些成员执行的一些任务。

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

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

保护文档的一部分时，会阻止用户更改或删除文档该部分的内容。 可通过多种方式使用内容控件保护文档的某些部分。

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

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

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

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

注释

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

有关如何使用内容控件保护文档部分的详细信息，请参阅 How to： Protect parts of documents by using content controls.

将数据绑定到内容控件

可以通过将内容控件绑定到数据源来显示文档中的数据。 更新数据源时，内容控件反映更改。 还可以将更改保存回数据源。

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

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

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

    有关将 Office 解决方案中的主机控件绑定到数据的概述，请参阅 将数据绑定到 Office 解决方案中的控件。

使用 Windows 窗体数据绑定模型

大多数内容控件都支持 Windows 窗体使用的简单数据绑定模型。 简单数据绑定意味着控件绑定到单个数据元素，例如数据表列中的值。 有关详细信息，请参阅 数据绑定和 Windows 窗体。

在文档级项目中，可以使用 Visual Studio 中的 “数据源 ”窗口将数据绑定到内容控件。 有关如何向文档添加数据绑定内容控件的详细信息，请参阅 How to： Populate documents with data from a database and How to： Populate documents with data from objects.

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

数据类型 默认内容控件 可绑定到此数据类型的其他内容控件
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Byte 数组		 PictureContentControl None

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

内容控件还支持双向数据绑定，其中控件中的更改将更新到数据源。 有关详细信息，请参阅 “如何：使用主机控件中的数据更新数据源”。

注释

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

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

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

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

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

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

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

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

内容控件的事件数据绑定

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

任务 事件 / 活动
在 Word 自动更新绑定到自定义 XML 部件的内容控件中的文本之前运行代码。 ContentUpdating
在 Word 自动更新绑定到内容控件的自定义 XML 部件中的数据之前（即内容控件中的文本发生更改时），运行代码。 StoreUpdating
运行自己的代码，根据自定义条件验证控件的内容。 Validating
成功验证控件内容后运行代码。 Validated

内容控件的限制

在 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 2010 引入了一种表示复选框的新型内容控件。 但是，Visual Studio Tools for Office 运行时不提供相应的 CheckBoxContentControl 类型供你在 Office 项目中使用。 若要在 Word 2013 或 Word 2010 项目中创建复选框内容控件，请使用 AddContentControl 该方法创建对象 ContentControl ，并将该值传递给 wdContentControlCheckBox 方法以指定复选框内容控件。 下面的代码示例演示如何执行此作。

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

相关内容