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

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

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

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

本演练阐释了以下任务：

• 设计时，将内容控件添加到文档级项目的 Word 文档。

• 创建定义元素以绑定到内容控件的 XML 数据文件和 XML 架构。

• 设计时，将 XML 架构附加到文档。

• 在运行时将 XML 文件的内容添加到文档中的自定义 XML 部件。

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

• 将 DropDownListContentControl 绑定到 XML 架构中定义的值集。

  注意

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

先决条件

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

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

• Microsoft Word。

创建新的 Word 文档项目

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

创建新的 Word 文档项目

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

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

向文档添加内容控件

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

若要将内容控件添加到文档

1. 在 Visual Studio 设计器中托管的 Word 文档中，在功能区上，选择“ 插入 ”选项卡。

2. 在 “表 ”组中，选择“ 表”，然后插入包含 2 列和 3 行的表。

3. 在第一列中键入文本，使之类似于以下列：

   员工姓名
   雇佣日期
   标题

4. 在表的第二列中，选择第一行（员工姓名旁）。

5. 在功能区上，选择“ 开发人员 ”选项卡。

   注意

   如果看不到 “开发人员” 选项卡，则必须首先显示它。 有关详细信息，请参阅 “如何：在功能区上显示开发人员”选项卡。

6. 在“控件”组中，选择“文本”按钮以向第一个单元格添加一个PlainTextContentControl。

7. 在表的第二列中，选择第二行（雇用日期旁）。

8. 在“控件”组中，选择“日期选取器”按钮以向第二个单元格添加一个DatePickerContentControl。

9. 在表的第二列中，选择第三行（标题旁边）。

10. 在“控件”组中，选择“下拉列表”按钮以向最后一个单元格添加一个DropDownListContentControl。

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

创建 XML 数据文件

通常情况下，你将获取 XML 数据存储在来自外部源（如文件或数据库）的自定义 XML 部件中。 在本演练中，你将创建包含员工数据的 XML 文件，此类数据由将绑定到文档中的内容控件的元素进行标记。 若要在运行时提供数据，请在自定义程序集中将 XML 文件嵌入为资源。

创建数据文件

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

   “添加新项” 对话框随即出现。

2. 在 “模板 ”窗格中，选择“ XML 文件”。

3. 将文件 命名为 employees.xml，然后选择“ 添加 ”按钮。

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

4. 将 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>
   

5. 在解决方案资源管理器中，选择 employees.xml 文件。

6. 在 “属性” 窗口中，选择“ 生成操作 ”属性，然后将该值更改为 “嵌入资源”。

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

创建 XML 架构

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

若要创建 XML 架构

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

   “添加新项” 对话框随即出现。

2. 在 “模板 ”窗格中，选择“ XML 架构”。

3. 将架构 命名为 employees.xsd ，然后选择“ 添加 ”按钮。

   架构设计器随即打开。

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

5. 将 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>
   

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

将 XML 架构附加到文档

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

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

1. 在设计器中激活 EmployeeControls.docx 。

2. 在功能区上，选择“ 开发人员 ”选项卡，然后选择 “加载项 ”按钮。

3. 在 “模板和外接程序 ”对话框中，选择 “XML 架构 ”选项卡，然后选择“ 添加架构 ”按钮。

4. 浏览到 之前创建的 employees.xsd 架构，该架构位于项目目录中，然后选择“ 打开 ”按钮。

5. 在“架构设置”对话框中选择“确定”按钮。

6. 选择 “确定 ”按钮以关闭 “模板和外接程序 ”对话框。

若要将 XML 架构附加到文档 (Word 2010)

1. 在设计器中激活 EmployeeControls.docx 。

2. 在功能区上，选择“ 开发人员 ”选项卡。

3. 在 XML 组中，选择“ 架构 ”按钮。

4. 在 “模板和外接程序 ”对话框中，选择 “XML 架构 ”选项卡，然后选择“ 添加架构 ”按钮。

5. 浏览到 之前创建的 employees.xsd 架构，该架构位于项目目录中，然后选择“ 打开 ”按钮。

6. 在“架构设置”对话框中选择“确定”按钮。

7. 选择 “确定 ”按钮以关闭 “模板和外接程序 ”对话框。

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

8. 关闭“XML 结构”任务窗格。

向文档添加自定义 XML 部件

在可以将内容控件绑定到 XML 文件中的元素之前，你必须将 XML 文件的内容添加到文档中的新自定义 XML 部件。

如要向文档添加自定义 XML 部件

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

2. 将以下声明添加到 ThisDocument 类。 此代码声明了将自定义 XML 部件添加到对象所用的几个对象。

   C#

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

   VB

   <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'"
   

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

   C#

   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;
   }
   

   VB

   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
   

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

   为确保只创建一次自定义 XML 部件，该方法仅在文档中不存在具有匹配 GUID 的自定义 XML 部件时，才会创建自定义 XML 部件。 第一次调用此方法时，该方法将 Id 属性的值保存为 employeeXMLPartID 字符串。 employeeXMLPartID 字符串的值将持久保存在文档中，因为该值是使用 CachedAttribute 属性声明的。

   C#

   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;
           }
       }
   }
   

   VB

   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 部件中的元素

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

   C#

   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);
   }
   

   VB

   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 部件并在打开文档后将自定义控件绑定到数据。

若要在打开文档后运行代码

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

   C#

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

   VB

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

测试项目

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

若要测试内容控件

1. 按 F5 运行项目。

2. 验证文档中的表格类似于下表。 第二列中的每个字符串的均来自文档的自定义 XML 部件中的元素。

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

3. 选择员工姓名单元格右侧的单元格并键入其他名称。

4. 选择“雇用日期”单元格右侧的单元格，然后在日期选取器中选择其他日期。

5. 选择标题单元格右侧的单元格，然后从下拉列表中选择一个新项。

6. 保存并关闭文档。

7. 在文件资源管理器中，打开项目位置下的 \bin\Debug 文件夹。

8. 打开 EmployeeControls.docx 的快捷菜单，然后选择“重命名”。

9. 将文件 命名为 EmployeeControls.docx.zip。

   EmployeeControls.docx 文档保存在 Open XML 格式中。 通过使用 .zip 文件扩展名重命名此文档，可以检查文档的内容。 有关 Open XML 的详细信息，请参阅介绍 办公室 （2007） Open XML 文件格式的技术文章。

10. 打开 EmployeeControls.docx.zip 文件。

11. 打开 customXml 文件夹。

12. 打开 item2.xml 的快捷菜单，然后选择“打开”。

    此文件包含已添加到文档的自定义 XML 部件。

13. 验证 name、hireDate 和 title 元素是否包含输入到文档中的内容控件中的新值。

14. 关闭 item2.xml 文件。

后续步骤

可从以下主题了解有关如何使用内容控件的更多信息：

• 使用所有可用的内容控件创建模板。 有关详细信息，请参阅 演练：使用内容控件创建模板。

• 关闭该文档时修改自定义 XML 部件中的数据。 下次用户打开文档时，绑定到的 XML 元素的内容控件将显示新的数据。

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

相关内容

• 使用扩展对象自动执行 Word
• 内容控件
• 如何：向 Word 文档添加内容控件
• 如何：使用内容控件保护文档的各个部分
• 主机项和主机控件概述
• 主机项和主机控件的编程限制
• 在运行时向办公室文档添加控件