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

2025-10-31

本演练演示如何将 Word 文档级自定义中的内容控件绑定到存储在文档中的 XML 数据。

适用于： 本主题中的信息适用于 Word 的文档级项目。有关详细信息，请参阅 Office 应用程序和项目类型提供的功能。

Word 使你能够在文档中存储名为 自定义 XML 部件的 XML 数据。可以通过将内容控件绑定到自定义 XML 部件中的元素来控制此数据的显示。本演练中的示例文档显示存储在自定义 XML 部件中的员工信息。打开文档时，内容控件将显示 XML 元素的值。对内容控件中的文本所做的任何更改都保存在自定义 XML 部件中。

本演练阐释了以下任务：

在设计时将内容控件添加到文档级项目中的 Word 文档。
创建 XML 数据文件和定义要绑定到内容控件的元素的 XML 架构。
在设计时将 XML 架构附加到文档。
在运行时将 XML 文件的内容添加到文档中的自定义 XML 部件。
将内容控件绑定到自定义 XML 部件中的元素。
将一个 DropDownListContentControl 绑定到 XML 架构中定义的一组值。

注释

以下说明中的某些 Visual Studio 用户界面元素在计算机上出现的名称或位置可能会不同。这些元素取决于你所使用的 Visual Studio 版本和你所使用的设置。有关详细信息，请参阅个性化设置 IDE。

先决条件

你需要满足以下条件才能完成本演练：

包含 Microsoft Office 开发人员工具的 Visual Studio 版本。有关详细信息，请参阅配置计算机以开发 Office 解决方案。
Microsoft Word。

创建新的 Word 文档项目

创建将在演练中使用的 Word 文档。

创建新的 Word 文档项目

创建名为 EmployeeControls 的 Word 文档项目。为解决方案创建新文档。有关详细信息，请参阅如何：在 Visual Studio 中创建 Office 项目。

Visual Studio 将在设计器中打开新的 Word 文档，并将 EmployeeControls 项目添加到 解决方案资源管理器。

向文档添加内容控件

创建一个表，其中包含三种不同类型的内容控件，用户可以在其中查看或编辑有关员工的信息。

向文档添加内容控件

在 Visual Studio 设计器中托管的 Word 文档中，在功能区上，选择 “插入 ”选项卡。
在 “表 ”组中，选择 “表”，然后插入包含 2 列和 3 行的表。
在第一列中输入文本，使其与以下列相似：

员工姓名

雇佣日期

标题
在表的第二列中，选择第一行（ 员工姓名旁）。
在功能区上，选择“ 开发人员 ”选项卡。

注释

如果 “开发人员 ”选项卡不可见，必须先显示它。有关详细信息，请参阅 “如何：在功能区上显示开发人员”选项卡。
在“控件”组中，选择“文本”按钮PlainTextContentControl以向第一个单元格中添加。
在表的第二列中，选择第二行（ 雇用日期旁）。
在 “控件 ”组中，选择 “日期选取器 ”按钮以向第二个单元格添加一个 DatePickerContentControl 。
在表的第二列中，选择第三行（标题旁边）。
在控件组中，选择下拉列表按钮，向最后一个单元格中添加一个 DropDownListContentControl。

这是此项目的整个用户界面。如果现在运行该项目，则可以在第一行中键入文本，然后选择第二行中的日期。下一步是将要显示的数据附加到 XML 文件中的文档。


员工姓名
雇佣日期
标题

创建 XML 数据文件

通常，你将从外部源（如文件或数据库）获取要存储在自定义 XML 部件中的 XML 数据。在本演练中，您将创建一个 XML 文件，其中包含员工数据，并通过元素标记这些数据以绑定到文档中的内容控件。若要在运行时提供数据，请在自定义程序集中将 XML 文件嵌入为资源。

创建数据文件

在 “项目” 菜单上，选择“ 添加新项”。

此时会显示“ 添加新项 ”对话框。
在 “模板 ”窗格中，选择 “XML 文件”。
将文件 命名为employees.xml，然后选择“ 添加 ”按钮。

employees.xml 文件将在代码编辑器中打开。

将 employees.xml 文件的内容替换为以下文本。

<?xml version="1.0" encoding="utf-8" ?>
<employees xmlns="http://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

在 解决方案资源管理器中，选择 employees.xml 文件。
在 “属性” 窗口中，选择 “生成作 ”属性，然后将该值更改为 “嵌入资源”。

在生成项目时，此步骤会将 XML 文件作为资源嵌入程序集中。这使你可以在运行时访问 XML 文件的内容。

创建 XML 架构

如果要将内容控件绑定到自定义 XML 部件中的单个元素，则无需使用 XML 架构。但是，若要绑定到 DropDownListContentControl 一组值，必须创建一个 XML 架构来验证之前创建的 XML 数据文件。 XML 架构定义元素的可能值 title 。在本演练中，您将在稍后将 DropDownListContentControl 绑定到此元素。

创建 XML 架构

在 “项目” 菜单上，选择“ 添加新项”。

此时会显示“ 添加新项 ”对话框。
在“ 模板 ”窗格中，选择 “XML 架构”。
将架构 命名为 employees.xsd ，然后选择 “添加 ”按钮。

架构设计器随即打开。
在 解决方案资源管理器中，打开 employees.xsd 的快捷菜单，然后选择“ 查看代码”。

将 employees.xsd 文件的内容替换为以下架构。

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="http://schemas.microsoft.com/vsto/samples"
    targetNamespace="http://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified">
  <xs:element name="employees" type="EmployeesType"></xs:element>
  <xs:complexType name="EmployeesType">
    <xs:all>
      <xs:element name="employee" type="EmployeeType"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="EmployeeType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
      <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="TitleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value ="Engineer"/>
      <xs:enumeration value ="Designer"/>
      <xs:enumeration value ="Manager"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

在“ 文件 ”菜单上，单击“ 全部保存 ”以保存 对employees.xml 和 employees.xsd 文件的更改。

将 XML 架构附加到文档

必须将 XML 架构附加到文档，以便将 DropDownListContentControl 绑定到 title 元素的有效值。

将 XML 架构附加到文档（Word 2013）

在设计器中激活 EmployeeControls.docx 。
在功能区上，选择 “开发人员 ”选项卡，然后选择 “加载项 ”按钮。
在 “模板和外接程序 ”对话框中，选择 “XML 架构 ”选项卡，然后选择“ 添加架构 ”按钮。
浏览到之前创建的 employees.xsd 架构，该架构位于项目目录中，然后选择“ 打开 ”按钮。
在“架构设置”对话框中选择“确定”按钮。
选择 “确定 ”按钮以关闭 “模板和外接程序 ”对话框。

将 XML 架构附加到文档（Word 2010）

在设计器中激活 EmployeeControls.docx 。
在功能区上，选择“ 开发人员 ”选项卡。
在 XML 组中，选择 “架构 ”按钮。
在 “模板和外接程序 ”对话框中，选择 “XML 架构 ”选项卡，然后选择“ 添加架构 ”按钮。
浏览到之前创建的 employees.xsd 架构，该架构位于项目目录中，然后选择“ 打开 ”按钮。
在“架构设置”对话框中选择“确定”按钮。
选择 “确定 ”按钮以关闭 “模板和外接程序 ”对话框。

此时会打开 “XML 结构 ”任务窗格。
关闭 “XML 结构 ”任务窗格。

向文档添加自定义 XML 部件

必须先将 XML 文件的内容添加到文档中的新自定义 XML 部件，然后才能将内容控件绑定到 XML 文件中的元素。

向文档添加自定义 XML 部件

在 解决方案资源管理器中，打开 ThisDocument.cs 或 ThisDocument.vb的快捷菜单，然后选择“ 查看代码”。

将以下声明添加到 ThisDocument 类。此代码声明将用于向文档添加自定义 XML 部件的多个对象。

[CachedAttribute()]
public string employeeXMLPartID = string.Empty;
private Office.CustomXMLPart employeeXMLPart;
private const string prefix = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'";

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'"

将以下方法添加到 ThisDocument 类。此方法获取作为程序集中的资源嵌入的 XML 数据文件的内容，并将内容作为 XML 字符串返回。

private string GetXmlFromResource()
{
    System.Reflection.Assembly asm =
        System.Reflection.Assembly.GetExecutingAssembly();
    System.IO.Stream stream1 = asm.GetManifestResourceStream(
        "EmployeeControls.employees.xml");

    using (System.IO.StreamReader resourceReader =
            new System.IO.StreamReader(stream1))
    {
        if (resourceReader != null)
        {
            return resourceReader.ReadToEnd();
        }
    }

    return null;
}

Private Function GetXmlFromResource() As String
    Dim asm As System.Reflection.Assembly = _
        System.Reflection.Assembly.GetExecutingAssembly()
    Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
            "EmployeeControls.employees.xml")

    Using resourceReader As System.IO.StreamReader = _
        New System.IO.StreamReader(stream1)
        If resourceReader IsNot Nothing Then
            Return resourceReader.ReadToEnd()
        End If
    End Using

    Return Nothing
End Function

将以下方法添加到 ThisDocument 类。该方法 AddCustomXmlPart 创建一个新的自定义 XML 部件，其中包含传递给该方法的 XML 字符串。

为了确保仅创建一次自定义 XML 部件，该方法仅在文档中尚不存在具有匹配 GUID 的自定义 XML 部件时创建自定义 XML 部件。首次调用此方法时，它将属性的值 Id 保存到 employeeXMLPartID 字符串中。字符串的值 employeeXMLPartID 保存在文档中，因为它是通过使用 CachedAttribute 属性声明的。

private void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"http://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

Private Sub AddCustomXmlPart(ByVal xmlData As String)
    If xmlData IsNot Nothing Then

        employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
        If (employeeXMLPart Is Nothing) Then
            employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
            employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                "http://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

将内容控件绑定到自定义 XML 部件中的元素

使用每个内容控件的 XMLMapping 属性将每个内容控件绑定到自定义 XML 部件中的元素。

将内容控件绑定到自定义 XML 部件中的元素

将以下方法添加到 ThisDocument 类。此方法将每个内容控件绑定到自定义 XML 部件中的元素，并设置 DatePickerContentControl 的日期显示格式。

private void BindControlsToCustomXmlPart()
{
    string xPathName = "ns:employees/ns:employee/ns:name";
    this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
        prefix, employeeXMLPart);

    string xPathDate = "ns:employees/ns:employee/ns:hireDate";
    this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
    this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
        prefix, employeeXMLPart);

    string xPathTitle = "ns:employees/ns:employee/ns:title";
    this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
        prefix, employeeXMLPart);
}

Private Sub BindControlsToCustomXmlPart()
    Dim xPathName As String = "ns:employees/ns:employee/ns:name"
    Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
        prefix, employeeXMLPart)

    Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
    Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
    Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
        prefix, employeeXMLPart)

    Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
    Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
        prefix, employeeXMLPart)
End Sub

打开文档时运行代码

创建自定义 XML 部件，并在打开文档时将自定义控件绑定到数据。

打开文档时运行代码

将以下代码添加到ThisDocument类的ThisDocument_Startup方法中。此代码从 employees.xml 文件中获取 XML 字符串，将 XML 字符串添加到文档中的新自定义 XML 部件，并将内容控件绑定到自定义 XML 部件中的元素。

string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}

Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If

测试项目

打开文档时，内容控件将显示自定义 XML 部件中元素中的数据。可以单击 DropDownListContentControl 以选择 title 元素的三个有效值之一，这些值是在 employees.xsd 文件中定义的。如果编辑任何内容控件中的数据，新值将保存在文档中的自定义 XML 部件中。

测试内容控件

按 F5 运行项目。
验证文档中的表是否类似于下表。第二列中的每一个字符串都是从文档中自定义 XML 部件中的元素获取的。

列价值

员工姓名 卡琳娜·莱尔

雇佣日期 1999 年 4 月 1 日

标题 Manager
选择 员工姓名 单元格右侧的单元格并键入其他名称。
选择 “雇用日期” 单元格右侧的单元格，然后在日期选取器中选择其他日期。
选择标题单元格右侧的单元格，然后从下拉列表中选择一个新项。
保存并关闭文档。
在文件资源管理器中，打开项目位置下的 \bin\Debug 文件夹。
打开 EmployeeControls.docx 的快捷菜单，然后选择“ 重命名”。
将文件 命名为EmployeeControls.docx.zip。

EmployeeControls.docx 文档以 Open XML 格式保存。通过使用 .zip 文件扩展名重命名此文档，可以检查文档的内容。有关 Open XML 的详细信息，请参阅 Office（2007） Open XML 文件格式简介的技术文章。
打开 EmployeeControls.docx.zip 文件。
打开 customXml 文件夹。
打开 item2.xml 的快捷菜单，然后选择“ 打开”。

此文件包含添加到文档的自定义 XML 部件。
验证文档中name、hireDate和title元素是否包含您在内容控件中输入的新值。
关闭 item2.xml 文件。

列	价值
员工姓名	卡琳娜·莱尔
雇佣日期	1999 年 4 月 1 日
标题	Manager

后续步骤

可以详细了解如何从以下主题使用内容控件：

使用所有可用的内容控件创建模板。有关详细信息，请参阅演练：使用内容控件创建模板。
关闭文档时修改自定义 XML 部件中的数据。下次用户打开文档时，绑定到 XML 元素的内容控件将显示新数据。
使用内容控件保护文档的某些部分。有关详细信息，请参阅如何：使用内容控件保护文档部分。

反馈

此页面是否有帮助？

通过

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

先决条件

创建新的 Word 文档项目

创建新的 Word 文档项目

向文档添加内容控件

向文档添加内容控件

创建 XML 数据文件

创建数据文件

创建 XML 架构

创建 XML 架构

将 XML 架构附加到文档

将 XML 架构附加到文档（Word 2013）

将 XML 架构附加到文档（Word 2010）

向文档添加自定义 XML 部件

向文档添加自定义 XML 部件

将内容控件绑定到自定义 XML 部件中的元素

将内容控件绑定到自定义 XML 部件中的元素

打开文档时运行代码

打开文档时运行代码

测试项目

测试内容控件

后续步骤

相关内容

反馈

其他资源