Przewodnik: wiązanie kontrolek zawartości z niestandardowymi częściami XML

W tym przewodniku pokazano, jak powiązać kontrolki zawartości w dostosowywaniu na poziomie dokumentu dla programu Word do danych XML przechowywanych w dokumencie.

Dotyczy: informacje w tym temacie dotyczą projektów na poziomie dokumentu dla programu Word. Aby uzyskać więcej informacji, zobacz Funkcje dostępne przez aplikacja pakietu Office lication i typ projektu.

Program Word umożliwia przechowywanie danych XML o nazwach niestandardowych części XML w dokumencie. Wyświetlanie tych danych można kontrolować przez powiązanie kontrolek zawartości z elementami w niestandardowej części XML. Przykładowy dokument w tym przewodniku zawiera informacje o pracownikach przechowywane w niestandardowej części XML. Po otwarciu dokumentu kontrolki zawartości wyświetlają wartości elementów XML. Wszelkie zmiany wprowadzone w tekście w kontrolkach zawartości są zapisywane w niestandardowej części XML.

W instruktażu przedstawiono następujące zagadnienia:

• Dodawanie kontrolek zawartości do dokumentu programu Word w projekcie na poziomie dokumentu w czasie projektowania.

• Tworzenie pliku danych XML i schematu XML definiującego elementy do powiązania z kontrolkami zawartości.

• Dołączanie schematu XML do dokumentu w czasie projektowania.

• Dodanie zawartości pliku XML do niestandardowej części XML w dokumencie w czasie wykonywania.

• Powiązanie kontrolek zawartości z elementami w niestandardowej części XML.

• Powiązanie elementu z DropDownListContentControl zestawem wartości zdefiniowanych w schemacie XML.

  Uwaga

  Na komputerze w poniższych instrukcjach mogą być wyświetlane inne nazwy i lokalizacje niektórych elementów interfejsu użytkownika programu Visual Studio. Te elementy są określane przez numer wersji Visual Studio oraz twoje ustawienia. Aby uzyskać więcej informacji, zobacz Personalizowanie środowiska IDE.

Wymagania wstępne

Następujące składniki są wymagane do przeprowadzenia tego instruktażu:

• Edycja programu Visual Studio, która oferuje narzędzia deweloperskie pakietu Microsoft Office. Aby uzyskać więcej informacji, zobacz Konfigurowanie komputera do tworzenia rozwiązań pakietu Office.

• Microsoft Word.

Tworzenie nowego projektu dokumentu programu Word

Utwórz dokument programu Word, który będzie używany w przewodniku.

Aby utworzyć nowy projekt dokumentu programu Word

1. Utwórz projekt dokumentu programu Word o nazwie EmployeeControls. Utwórz nowy dokument dla rozwiązania. Aby uzyskać więcej informacji, zobacz How to: Create Office projects in Visual Studio (Jak tworzyć projekty pakietu Office w programie Visual Studio).

   Program Visual Studio otwiera nowy dokument programu Word w projektancie i dodaje projekt EmployeeControls do Eksplorator rozwiązań.

Dodawanie kontrolek zawartości do dokumentu

Utwórz tabelę zawierającą trzy różne typy kontrolek zawartości, w których użytkownik może wyświetlać lub edytować informacje o pracowniku.

Aby dodać kontrolki zawartości do dokumentu

1. W dokumencie programu Word hostowanym w projektancie programu Visual Studio na wstążce wybierz kartę Wstawianie .

2. W grupie Tabele wybierz pozycję Tabela i wstaw tabelę z 2 kolumnami i 3 wierszami.

3. Wpisz tekst w pierwszej kolumnie, tak aby przypominał następującą kolumnę:

   Imię i nazwisko pracownika
   Data zatrudnienia
   Tytuł

4. W drugiej kolumnie tabeli wybierz pierwszy wiersz (obok pozycji Nazwa pracownika).

5. Na wstążce wybierz kartę Deweloper .

   Uwaga

   Jeśli karta Deweloper nie jest widoczna, musisz go najpierw wyświetlić. Aby uzyskać więcej informacji, zobacz Instrukcje: pokazywanie karty dewelopera na wstążce.

6. W grupie Kontrolki wybierz przycisk Tekst, aby dodać PlainTextContentControl elementdo pierwszej komórki.

7. W drugiej kolumnie tabeli wybierz drugi wiersz (obok pozycji Data zatrudnienia).

8. W grupie Kontrolki wybierz przycisk Selektor dat, aby dodać elementDatePickerContentControldo drugiej komórki.

9. W drugiej kolumnie tabeli wybierz trzeci wiersz (obok pozycji Tytuł).

10. W grupie Kontrolki wybierz przycisk Lista rozwijana, aby dodać DropDownListContentControl elementdo ostatniej komórki.

    Jest to cały interfejs użytkownika dla tego projektu. Jeśli teraz uruchomisz projekt, możesz wpisać tekst w pierwszym wierszu i wybrać datę w drugim wierszu. Następnym krokiem jest dołączenie danych, które mają być wyświetlane w dokumencie w pliku XML.

Tworzenie pliku danych XML

Zazwyczaj dane XML będą przechowywane w niestandardowej części XML ze źródła zewnętrznego, takiego jak plik lub baza danych. W tym przewodniku utworzysz plik XML zawierający dane pracownika oznaczony elementami, które zostaną powiązane z kontrolkami zawartości w dokumencie. Aby udostępnić dane w czasie wykonywania, osadź plik XML jako zasób w zestawie dostosowywania.

Aby utworzyć plik danych

1. W menu Project (Projekt) wybierz pozycję Add New Item (Dodaj nowy element).

   Zostanie wyświetlone okno dialogowe Dodawanie nowego elementu.

2. W okienku Szablony wybierz pozycję Plik XML.

3. Nadaj plikowi nazwę employees.xml, a następnie wybierz przycisk Dodaj .

   Plik employees.xml zostanie otwarty w Edytorze kodu.

4. Zastąp zawartość pliku employees.xml następującym tekstem.

   <?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. W Eksplorator rozwiązań wybierz plik employees.xml.

6. W oknie Właściwości wybierz właściwość Akcja kompilacji, a następnie zmień wartość na Zasób osadzony.

   Ten krok osadza plik XML jako zasób w zestawie podczas kompilowanie projektu. Dzięki temu można uzyskać dostęp do zawartości pliku XML w czasie wykonywania.

Tworzenie schematu XML

Jeśli chcesz powiązać kontrolkę zawartości z jednym elementem w niestandardowej części XML, nie musisz używać schematu XML. Aby jednak powiązać element z DropDownListContentControl zestawem wartości, należy utworzyć schemat XML, który weryfikuje utworzony wcześniej plik danych XML. Schemat XML definiuje możliwe wartości elementu title . Powiążesz element z DropDownListContentControl tym elementem w dalszej części tego przewodnika.

Aby utworzyć schemat XML

1. W menu Project (Projekt) wybierz pozycję Add New Item (Dodaj nowy element).

   Zostanie wyświetlone okno dialogowe Dodawanie nowego elementu.

2. W okienku Szablony wybierz pozycję Schemat XML.

3. Nadaj schematowi nazwę employees.xsd i wybierz przycisk Dodaj .

   Zostanie otwarty projektant schematu.

4. W Eksplorator rozwiązań otwórz menu skrótów dla pliku employees.xsd, a następnie wybierz pozycję Wyświetl kod.

5. Zastąp zawartość pliku employees.xsd następującym schematem.

   <?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. W menu Plik kliknij pozycję Zapisz wszystko, aby zapisać zmiany w plikach employees.xml i employees.xsd.

Dołączanie schematu XML do dokumentu

Należy dołączyć schemat XML do dokumentu, aby powiązać element z DropDownListContentControl prawidłowymi wartościami title elementu.

Aby dołączyć schemat XML do dokumentu ( Word 2013 )

1. Aktywuj plik EmployeeControls.docx w projektancie.

2. Na wstążce wybierz kartę Deweloper , a następnie wybierz przycisk Dodatki .

3. W oknie dialogowym Szablony i dodatki wybierz kartę Schemat XML, a następnie wybierz przycisk Dodaj schemat.

4. Przejdź do utworzonego wcześniej schematu employees.xsd , który znajduje się w katalogu projektu, a następnie wybierz przycisk Otwórz .

5. Wybierz przycisk OK w oknie dialogowym Schemat Ustawienia.

6. Wybierz przycisk OK, aby zamknąć okno dialogowe Szablony i dodatki.

Aby dołączyć schemat XML do dokumentu (Word 2010)

1. Aktywuj plik EmployeeControls.docx w projektancie.

2. Na wstążce wybierz kartę Deweloper .

3. W grupie XML wybierz przycisk Schemat.

4. W oknie dialogowym Szablony i dodatki wybierz kartę Schemat XML, a następnie wybierz przycisk Dodaj schemat.

5. Przejdź do utworzonego wcześniej schematu employees.xsd , który znajduje się w katalogu projektu, a następnie wybierz przycisk Otwórz .

6. Wybierz przycisk OK w oknie dialogowym Schemat Ustawienia.

7. Wybierz przycisk OK, aby zamknąć okno dialogowe Szablony i dodatki.

   Zostanie otwarte okienko zadań Struktura XML.

8. Zamknij okienko zadań Struktura XML.

Dodawanie niestandardowej części XML do dokumentu

Aby można było powiązać kontrolki zawartości z elementami w pliku XML, należy dodać zawartość pliku XML do nowej niestandardowej części XML w dokumencie.

Aby dodać niestandardową część XML do dokumentu

1. W Eksplorator rozwiązań otwórz menu skrótów dla pliku ThisDocument.cs lub ThisDocument.vb, a następnie wybierz pozycję Wyświetl kod.

2. Dodaj następujące deklaracje do ThisDocument klasy . Ten kod deklaruje kilka obiektów, których użyjesz do dodania niestandardowej części XML do dokumentu.

   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. Dodaj następującą metodę do ThisDocument klasy . Ta metoda pobiera zawartość pliku danych XML osadzonego jako zasób w zestawie i zwraca zawartość jako ciąg 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. Dodaj następującą metodę do ThisDocument klasy . Metoda AddCustomXmlPart tworzy nową niestandardową część XML zawierającą ciąg XML przekazywany do metody.

   Aby upewnić się, że niestandardowa część XML jest tworzona tylko raz, metoda tworzy niestandardową część XML tylko wtedy, gdy niestandardowa część XML z pasującym identyfikatorem GUID nie istnieje jeszcze w dokumencie. Przy pierwszej wywołaniu tej metody zapisuje wartość Id właściwości w employeeXMLPartID ciągu. Wartość employeeXMLPartID ciągu jest utrwalana w dokumencie, ponieważ została zadeklarowana przy użyciu atrybutu 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
   

Wiązanie kontrolek zawartości z elementami w niestandardowej części XML

Powiąż każdą kontrolkę zawartości z elementem w niestandardowej części XML przy użyciu właściwości XMLMapping każdej kontrolki zawartości.

Aby powiązać kontrolki zawartości z elementami w niestandardowej części XML

1. Dodaj następującą metodę do ThisDocument klasy . Ta metoda wiąże każdą kontrolkę zawartości z elementem w niestandardowej części XML i ustawia format wyświetlania daty .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
   

Uruchamianie kodu po otwarciu dokumentu

Utwórz niestandardową część XML i powiąż niestandardowe kontrolki z danymi po otwarciu dokumentu.

Aby uruchomić kod po otwarciu dokumentu

1. Dodaj następujący kod do ThisDocument_Startup metody ThisDocument klasy . Ten kod pobiera ciąg XML z pliku employees.xml , dodaje ciąg XML do nowej niestandardowej części XML w dokumencie i wiąże kontrolki zawartości z elementami w niestandardowej części 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
   

Testowanie projektu

Po otwarciu dokumentu kontrolki zawartości wyświetlają dane z elementów w niestandardowej części XML. Możesz kliknąć element , DropDownListContentControl aby wybrać jedną z trzech prawidłowych wartości dla title elementu, które są zdefiniowane w pliku employees.xsd . Jeśli edytujesz dane w dowolnych kontrolkach zawartości, nowe wartości zostaną zapisane w niestandardowej części XML w dokumencie.

Aby przetestować kontrolki zawartości

1. Naciśnij klawisz F5 , aby uruchomić projekt.

2. Sprawdź, czy tabela w dokumencie przypomina poniższą tabelę. Każdy z ciągów w drugiej kolumnie jest uzyskiwany z elementu w niestandardowej części XML w dokumencie.

   Kolumna	Wartość
   Imię i nazwisko pracownika	Karina Leal
   Data zatrudnienia	1 kwietnia 1999 r.
   Tytuł	Menedżer

3. Wybierz komórkę z prawej strony komórki Nazwa pracownika i wpisz inną nazwę.

4. Wybierz komórkę z prawej strony komórki Data zatrudnienia i wybierz inną datę w selektorze dat.

5. Wybierz komórkę z prawej strony komórki Tytuł i wybierz nowy element z listy rozwijanej.

6. Zapisz i zamknij dokument.

7. W Eksplorator plików otwórz folder \bin\Debug w lokalizacji projektu.

8. Otwórz menu skrótów dla pliku EmployeeControls.docx , a następnie wybierz pozycję Zmień nazwę.

9. Nadaj plikowi nazwę EmployeeControls.docx.zip.

   Dokument EmployeeControls.docx jest zapisywany w formacie Open XML. Zmiana nazwy tego dokumentu przy użyciu rozszerzenia nazwy pliku zip umożliwia sprawdzenie zawartości dokumentu. Aby uzyskać więcej informacji na temat programu Open XML, zobacz artykuł techniczny Wprowadzenie do formatów plików Open XML pakietu Office (2007).

10. Otwórz plik EmployeeControls.docx.zip.

11. Otwórz folder customXml.

12. Otwórz menu skrótów dla pliku item2.xml , a następnie wybierz pozycję Otwórz.

    Ten plik zawiera niestandardową część XML dodaną do dokumentu.

13. Sprawdź, czy nameelementy , hireDatei title zawierają nowe wartości wprowadzone w kontrolkach zawartości w dokumencie.

14. Zamknij plik item2.xml.

Następne kroki

Więcej informacji na temat używania kontrolek zawartości można znaleźć w następujących tematach:

• Użyj wszystkich dostępnych kontrolek zawartości, aby utworzyć szablon. Aby uzyskać więcej informacji, zobacz Przewodnik: tworzenie szablonu przy użyciu kontrolek zawartości.

• Zmodyfikuj dane w niestandardowych częściach XML, gdy dokument jest zamknięty. Następnym razem, gdy użytkownik otworzy dokument, kontrolki zawartości powiązane z elementami XML będą wyświetlać nowe dane.

• Użyj kontrolek zawartości, aby chronić części dokumentu. Aby uzyskać więcej informacji, zobacz Jak chronić części dokumentów przy użyciu kontrolek zawartości.

Powiązana zawartość

• Automatyzowanie programu Word przy użyciu obiektów rozszerzonych
• Kontrolki zawartości
• Instrukcje: dodawanie kontrolek zawartości do dokumentów programu Word
• Instrukcje: ochrona części dokumentów przy użyciu kontrolek zawartości
• Omówienie elementów hosta i kontrolek hosta
• Ograniczenia programowe elementów hosta i kontrolek hosta
• Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania