内容控件
利用内容控件可以设计具有以下功能的文档和模板：
一个用户界面 (UI)，其中包含类似于窗体的受控输入。
可防止用户编辑文档或模板受保护部分的限制。 有关更多信息，请参见使用内容控件保护文档的各个部分。
到数据源的数据绑定。 有关更多信息，请参见将数据绑定到内容控件。
**适用于：**本主题中的信息适用于 Word 2007 和 Word 2010 的文档级项目和应用程序级项目。有关更多信息，请参见按 Office 应用程序和项目类型提供的功能。
.gif "链接到视频")
有关相关的视频演示，请参见 Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0)（使用 Visual Studio Tools for the Office system (3.0) 将数据绑定到 Word 2007 内容控件）。
内容控件概述
内容控件提供了一个同时针对用户输入和打印优化过的 UI。 向文档中添加内容控件时，控件由边框、标题和可向用户提供说明的临时文本标识。 控件的边框和标题不会出现在文档的打印版本中。
例如，如果希望用户在文档的某个部分中输入日期，您可以向文档中添加日期选择器内容控件。 当用户单击该控件时，将出现标准的日期选择器 UI。 您还可以设置该控件的属性，以便设置显示的区域日历和指定日期格式。 用户选择了日期后，控件的 UI 将隐藏，并且，如果用户打印文档，只有日期会出现。
内容控件还可帮助您执行下列操作：
防止用户编辑或删除文档的某些部分。 如果文档或模板上有用户应能够读取但不能编辑的信息，或者，如果您希望用户能够编辑但不能删除内容控件，这一点非常有用。
将文档或模板的各部分绑定到数据。 可以将内容控件绑定到数据库字段、.NET Framework 中的托管对象、存储在文档中的 XML 元素以及其他数据源。
在文档级项目中，您可以在设计时或运行时向文档中添加内容控件。 在应用程序级项目中，可以在运行时向任何打开的文档中添加内容控件。 有关更多信息，请参见如何：向 Word 文档添加内容控件。
提示
您只能在以 Open XML 格式保存的文档中使用内容控件。 您不能在以 Word 97-2003 文档 (.doc) 格式保存的文档中使用内容控件。
内容控件的类型
可添加到文档中的内容控件共有九种不同类型。 大多数内容控件在 Microsoft.Office.Tools.Word 命名空间中都有对应的类型。 也可以使用泛型 ContentControl，该类型可表示任何可用的内容控件。 有关演示如何使用每种可用内容控件的演练，请参见演练：使用内容控件创建模板。
生成块库
生成块库使用户能够从“文档生成块”的列表中进行选择以插入文档。 文档生成块是创建用来重复使用的一部分内容，例如共用封面页、带格式的表或标题。 有关更多信息，请参见 BuildingBlockGalleryContentControl 类型。 有关生成块的更多信息，请参见 Word 2007 针对开发人员的新功能。
复选框
复选框提供表示二进制状态的 UI：选中或清除。 此类型的内容控件只在 Word 2010 中可用。
与其他类型的内容控件不同，Visual Studio Tools for Office Runtime 不提供表示复选框内容控件的特定类型。 换句话说，没有 CheckBoxContentControl 类型。 但是，仍然可以通过以编程方式向文档中添加泛型 ContentControl 来创建复选框内容控件。 有关更多信息，请参见 Word 2010 项目中的复选框内容控件。
组合框
组合框显示用户可以选择的项列表。 与下拉列表不同，组合框允许用户添加自己的项。 有关更多信息，请参见 ComboBoxContentControl 类型。
日期选择器
日期选择器提供一个用于选择日期的日历 UI。 在最终用户单击该控件中的下拉箭头时，日历将会出现。 您可以使用区域日历和不同的日期格式。 有关更多信息，请参见 DatePickerContentControl 类型。
下拉列表
下拉列表显示用户可以选择的项列表。 与组合框不同，下拉列表不允许用户添加或编辑项。 有关更多信息，请参见 DropDownListContentControl 类型。
组
组控件定义用户无法编辑或删除的受保护文档区域。 组控件可包含任何文档项，比如文本、表格、图形以及其他内容控件。 有关更多信息，请参见 GroupContentControl 类型。
图片
图片控件可显示图像。 您可以在设计时或运行时指定图像，或者用户可以单击此控件来选择插入到文档中的图像。 有关更多信息，请参见 PictureContentControl 类型。
多格式文本
多格式文本控件包含文本或其他项，比如表格、图片或其他内容控件。 有关更多信息，请参见 RichTextContentControl 类型。
纯文本
纯文本控件包含文本。 纯文本控件无法包含其他项，比如表格、图片或其他内容控件。 此外，纯文本控件中的所有文本都具有相同的格式设置。 例如，如果将纯文本控件中某个句子的一个单词设置为斜体，则该控件中的所有文本都将设置为斜体。 有关更多信息，请参见 PlainTextContentControl 类型。
泛型内容控件
泛型内容控件是 ContentControl 对象，它可表示任何可用类型的内容控件。 通过使用 Type 属性，您可以更改 ContentControl 对象，以使其具有类似于其他类型内容控件的行为。 例如，如果创建了表示纯文本控件的 ContentControl 对象，则可以在运行时对其进行更改，使之具有类似于组合框的行为。
只能在运行时创建 ContentControl 对象，而不能在设计时创建。 有关更多信息，请参见如何：向 Word 文档添加内容控件。
内容控件的公共特性
大部分内容控件都有一组您可用于执行常规任务的成员。 下表描述了您可以使用这些成员执行的一些任务。
对于此任务： |
执行此操作： |
|---|---|
获取或设置控件中显示的文本。 |
使用 Text 属性。 .gif "注意") 注意
PictureContentControl 和 ContentControl 类型没有此属性。
|
获取或设置临时文本，在用户编辑控件、用数据源中的数据填充控件，或者控件内容被删除之前，临时文本将显示在控件中。 |
使用 PlaceholderText 属性。 注意
PictureContentControl 类型没有此属性。
|
获取或设置当用户单击内容控件时显示在该控件边框中的标题。 |
使用 Title 属性。 |
在用户编辑控件后从文档中自动移除控件。 （控件中的文本将保留在文档中。） |
使用 Temporary 属性。 |
在用户单击内容控件时，或者当光标通过编程方式移入内容控件时运行代码。 |
处理控件的 Entering 事件。 |
在用户单击内容控件外部时，或者当光标通过编程方式移出内容控件时运行代码。 |
处理控件的 Exiting 事件。 |
在由于重做或撤消操作而将内容控件添加到文档后运行代码。 |
处理控件的 Added 事件。 |
在内容控件从文档中删除之前运行代码。 |
处理控件的 Deleting 事件。 |
使用内容控件保护文档的各个部分
如果保护文档的某个部分，将会防止用户更改或删除文档该部分中的内容。 可通过多种方式用内容控件来保护文档的各个部分。
如果要保护的区域在内容控件内部，您可以使用内容控件的属性来防止用户编辑或删除控件：
LockContents 属性可防止用户编辑内容。
LockContentControl 属性可防止用户删除控件。
如果要保护的区域不在内容控件内部，或者，如果要保护包含内容控件和其他类型内容的区域，您可以将整个区域放在 GroupContentControl 中。 与其他内容控件不同，GroupContentControl 未提供用户可看到的 UI。 它的唯一用途是定义一个用户无法编辑的区域。
提示
如果创建一个包含嵌入式内容控件的 GroupContentControl，则不会自动保护这些嵌入式内容控件。 必须使用每个嵌入式控件的 LockContents 属性来防止用户编辑控件的内容。
有关如何使用内容控件来保护文档各部分的更多信息，请参见如何：使用内容控件保护文档的某些部分。
将数据绑定到内容控件
可以通过将内容控件绑定到数据源而在文档中显示数据。 数据源更新后，内容控件将反映更改。 您也可以将更改保存回数据源。
内容控件提供了以下数据绑定选项：
可以使用与 Windows 窗体相同的数据绑定模型将内容控件绑定到数据库字段或托管对象。
可将内容控件绑定到嵌入在文档中的 XML 段（也称为“自定义 XML 部件”）内的元素。
有关将 Office 解决方案中的宿主控件绑定到数据的概述，请参见将数据绑定到 Office 解决方案中的控件。
使用 Windows 窗体数据绑定模型
大多数内容控件都支持 Windows 窗体使用的简单数据绑定模型。 简单数据绑定意指将控件绑定到单个数据元素，比如数据表某列中的一个值。 有关更多信息，请参见数据绑定和 Windows 窗体。
在文档级项目中，可以使用 Visual Studio 中的**“数据源”**窗口将数据绑定到内容控件。 有关如何向文档中添加数据绑定内容控件的更多信息，请参见如何：用数据库中的数据填充文档和如何：用对象中的数据填充文档。
下表列出了您可在**“数据源”**窗口中绑定到每种数据类型的内容控件。
数据类型 |
默认内容控件 |
可绑定到此数据类型的其他内容控件 |
|---|---|---|
|
Byte 数组 |
无 |
在文档级和应用程序级项目中，可以使用内容控件的 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 部件：
内容控件的数据绑定事件
所有内容控件都提供了一组您可进行处理以执行数据相关任务（比如在更新数据源之前验证控件中的文本是否满足特定条件）的事件。 下表列出了与数据绑定相关的内容控件事件。
任务 |
Event |
|---|---|
恰好在 Word 自动更新绑定到自定义 XML 部件的内容控件中的文本之前运行代码。 |
|
恰好在 Word 自动更新绑定到内容控件的自定义 XML 部件中的数据之前（即在内容控件中的文本更改之后）运行代码。 |
|
运行自己的代码，以便依据自定义条件验证控件的内容。 |
|
在成功验证控件的内容后运行代码。 |
内容控件的限制
在 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 2010 项目中的复选框内容控件
Word 2010 引入了一种新的内容控件类型，这种控件表示复选框。 不过，Visual Studio Tools for Office Runtime 未提供在 Office 项目中使用的相应 CheckBoxContentControl 类型。 若要在 Word 2010 项目中创建复选框内容控件，请使用 AddContentControl 方法创建 Microsoft.Office.Tools.Word.ContentControl 对象，并将 wdContentControlCheckBox 值传递给该方法以指定复选框内容控件。 下面的代码示例演示如何执行此操作。
Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)
' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True
' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True
this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 =
this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);
// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;
// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;
提示
Microsoft.Office.Tools.Word.ContentControl 对象的 Checked 属性仅能直接在面向 .NET Framework 4 的项目中使用。 在以 .NET Framework 3.5 为目标的项目中，必须使用 InnerObject 属性来访问基础的 Microsoft.Office.Interop.Word.ContentControl 对象的 Checked 属性。 有关更多信息，请参见宿主项和宿主控件的编程限制。