逐步解說:將內容控制項繫結至自訂 XML 組件

更新:2007 年 11 月

適用於

本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。

專案類型

  • 文件層級專案

Microsoft Office 版本

  • Word 2007

如需詳細資訊,請參閱依應用程式和專案類型提供的功能

本逐步解說示範如何使用 Word 2007 文件層級自訂,將內容控制項繫結至文件中所儲存的 XML 資料。

Word 2007 可讓您在文件中儲存「自訂 XML 組件」(Custom XML Part) 的 XML 資料。您可以將內容控制項繫結至自訂 XML 組件中的項目,藉以控制此資料的顯示。本逐步解說中的範例文件會顯示已儲存於自訂 XML 組件中的員工資訊。當您開啟文件時,內容控制項會顯示 XML 項目的值。您對內容控制項文字所進行的變更都會儲存在自訂 XML 組件中。

這個逐步解說將說明下列工作:

  • 在設計階段,透過文件層級專案將內容控制項加入至 Word 文件。

  • 建立 XML 資料檔案和 XML 結構描述,以定義要繫結至內容控制項的項目。

  • 在設計階段將 XML 結構描述附加至文件。

  • 在執行階段將 XML 檔案的內容加入至文件中的自訂 XML 組件。

  • 將內容控制項繫結至自訂 XML 組件中的項目。

  • DropDownListContentControl 繫結至 XML 結構描述中所定義的一組值。

注意事項:

您的電腦可能會在下列說明中,以不同名稱或位置顯示某些 Visual Studio 使用者介面項目。您所擁有的 Visual Studio 版本以及使用的設定會決定這些項目。如需詳細資訊,請參閱 Visual Studio 設定

必要條件

您需要下列元件才能完成此逐步解說:

  • Visual Studio Tools for Office (Visual Studio 2008 Professional 和 Visual Studio Team System 的選擇性元件)。

  • Microsoft Office Word 2007

Visual Studio Tools for Office 預設會與列出的 Visual Studio 版本一起安裝。若要查看是否已安裝,請參閱 安裝 Visual Studio Tools for Office

建立新的 Word 文件專案

建立您將用於本逐步解說中的 Word 2007 文件。

若要建立新的 Word 2007 文件專案

  • 使用 2007 Microsoft Office system 的 Word 文件專案範本,建立名稱為 EmployeeControls 的 Word 文件專案。建立方案的新文件。如需詳細資訊,請參閱 HOW TO:建立 Visual Studio Tools for Office 專案

    Visual Studio 會在設計工具中開啟新的 Word 文件,並將 EmployeeControls 專案加入至 [方案總管]。

將內容控制項加入至文件

建立含有三種不同內容控制項的資料表,使用者可以在這個資料表中檢視或編輯員工資訊。

若要將內容控制項加入至文件

  1. 在 Visual Studio 設計工具裝載的 Word 文件中,按一下功能區上的 [插入] 索引標籤。

  2. 按一下 [資料表] 群組中的 [資料表],並插入具有 2 欄 3 列的資料表。

  3. 請在第一欄中輸入文字,使該欄看起來像下面這一個資料行:

    員工姓名

    雇用日期

    職稱

  4. 在資料表的第二欄中,按一下第一列 ([員工姓名] 旁邊)。

  5. 按一下 [功能區] 上的 [開發人員] 索引標籤。

    注意事項:

    如果 [開發人員] 索引標籤沒有顯示,您必須先使其顯示。如需詳細資訊,請參閱 HOW TO:在功能區顯示開發人員索引標籤

  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 結構描述附加至文件

  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 類別 (Class)。這個程式碼會宣告數個物件,您可以使用這些物件將自訂 XML 組件加入至文件。

    <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'"
    
    [CachedAttribute()]
    public string employeeXMLPartID = string.Empty;
    private Office.CustomXMLPart employeeXMLPart;
    private const string prefix = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'";
    
  3. 將下列方法加入至 ThisDocument 類別。這個方法會取得已內嵌在組件中成為資源的 XML 資料檔案的內容,並將此內容當做 XML 字串傳回。

    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
    
    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;
    }
    
  4. 將下列方法加入至 ThisDocument 類別。AddCustomXmlPart 方法會建立新的自訂 XML 組件,該組件含有傳遞給此方法的 XML 字串。

    為了要確保僅建立一次自訂 XML 組件,只有當文件中不存在具有相符 GUID 的自訂 XML 組件時,這個方法才會建立自訂 XML 組件。第一次呼叫這個方法時,它會將 Microsoft.Office.Interop.Word.CustomXMLPart.Id 屬性 (Property) 的值儲存至 employeeXMLPartID 字串。employeeXMLPartID 字串的值會保存在文件中,因為這是使用 CachedAttribute 屬性 (Attribute) 所宣告的。

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

將內容控制項繫結至自訂 XML 組件中的項目

使用每個內容控制項的 XMLMapping 屬性 (Property),將每個內容控制項繫結至自訂 XML 組件中的項目。

若要將內容控制項繫結至自訂 XML 組件中的項目

  • 將下列方法加入至 ThisDocument 類別。這個方法會將每個內容控制項繫結至自訂 XML 組件中的項目,並且設定 DatePickerContentControl 的日期顯示格式。

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

在文件開啟時執行程式碼

建立自訂 XML 組件,並且在文件開啟時將自訂控制項繫結至資料。

若要在文件開啟時執行程式碼

  • 將下列程式碼加入至 ThisDocument 類別的 ThisDocument_Startup。這個程式碼會從 employees.xml 檔取得 XML 字串、將 XML 字串加入至文件中新的自訂 XML 組件,並且將內容控制項繫結至自訂 XML 組件中的項目。

    Dim xmlData As String = GetXmlFromResource()
    If xmlData IsNot Nothing Then
        AddCustomXmlPart(xmlData)
        BindControlsToCustomXmlPart()
    End If
    
    string xmlData = GetXmlFromResource();
    
    if (xmlData != null)
    {
        AddCustomXmlPart(xmlData);
        BindControlsToCustomXmlPart();
    }
    

測試專案

當您開啟文件時,內容控制項會顯示自訂 XML 組件中的項目資料。您可以按一下 DropDownListContentControl 選取 title 項目的三個有效值之一 (這些值定義於 employees.xsd 檔案中)。如果您編輯任何內容控制項中的資料,新值就會儲存在文件的自訂 XML 組件中。

若要測試內容控制項

  1. 請按 F5 執行專案。

  2. 確認文件中的資料表類似下列資料表。第二欄中的每個字串都是從文件之自訂 XML 組件中的項目取得。

    員工姓名

    Karina Leal

    雇用日期

    April 1, 1999

    職稱

    主管

  3. 按一下 [員工姓名] 儲存格右邊的儲存格,並且輸入不同的名稱。

  4. 按一下 [雇用日期] 儲存格右邊的儲存格,並且在日期選擇器中選取不同的日期。

  5. 按一下 [職稱] 儲存格右邊的儲存格,並從下拉式清單中選取新項目。

  6. 儲存並關閉文件。

  7. 在 Windows 檔案總管中,開啟專案所在位置下的 \bin\Debug 資料夾。

  8. 以滑鼠右鍵按一下 EmployeeControls.docx,然後按一下 [重新命名]。

  9. 將檔案命名為 EmployeeControls.docx.zip。

    EmployeeControls.docx 文件會以 Open XML 格式儲存。將此文件的副檔名重新命名為 .zip,您即可檢查文件的內容。如需 Open XML 格式的詳細資訊,請參閱 Open XML 檔案格式簡介技術文件。

  10. 按兩下 EmployeeControls.docx.zip 檔案。

  11. 按兩下 customXml 資料夾。

  12. 以滑鼠右鍵按一下 item2.xml,然後按一下 [開啟]。

    這個檔案包含您加入至文件的自訂 XML 組件。

  13. 確認 name、hireDate 和 title 項目包含您在文件的內容控制項中輸入的新值。

  14. 關閉 item2.xml 檔案。

後續步驟

您可以透過下列主題,進一步了解使用內容控制項的方式:

請參閱

工作

HOW TO:將內容控制項加入至 Word 文件

HOW TO:使用內容控制項保護文件的部分

概念

內容控制項

主項目和主控制項概觀

主項目和主控制項的程式設計限制

在執行階段將控制項加入至 Office 文件

主控制項的 Helper 方法

其他資源

Word 主控制項