Procédure pas à pas : lier des contrôles de contenu à des parties XML personnalisées

Cette procédure pas à pas montre comment lier les contrôles de contenu d'une personnalisation au niveau du document pour Word aux données XML stockées dans le document.

S’applique à : les informations de cette rubrique s’appliquent aux projets au niveau du document pour Word. Pour plus d’informations, consultez Fonctionnalités disponibles par application Office lication et le type de projet.

Word vous permet de stocker des données XML, nommées parties XML personnalisées, dans un document. Vous pouvez contrôler l'affichage de ces données en liant les contrôles de contenu aux éléments d'une partie XML personnalisée. L'exemple de document de cette procédure pas à pas affiche les informations sur les employés qui sont stockées dans une partie XML personnalisée. Lorsque vous ouvrez le document, les contrôles de contenu affichent les valeurs des éléments XML. Les modifications que vous apportez au texte des contrôles de contenu sont enregistrées dans la partie XML personnalisée.

Cette procédure pas à pas décrit les tâches suivantes :

• Ajout de contrôles de contenu au document Word d'un projet de niveau document au moment du design.

• Création d'un fichier de données XML et d'un schéma XML qui définit les éléments à lier aux contrôles de contenu.

• Liaison du schéma XML au document au moment du design.

• Ajout du contenu du fichier XML à un composant XML personnalisé dans le document au moment de l’exécution.

• Liaison des contrôles de contenu aux éléments de la partie XML personnalisée.

• Liaison d’un DropDownListContentControl à un ensemble de valeurs définies dans le schéma XML.

  Remarque

  Il est possible que pour certains des éléments de l'interface utilisateur de Visual Studio, votre ordinateur affiche des noms ou des emplacements différents de ceux indiqués dans les instructions suivantes. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d’informations, consultez Personnaliser l’IDE.

Prérequis

Vous devez disposer des éléments suivants pour exécuter cette procédure pas à pas :

• Une édition de Visual Studio qui inclut les outils de développement Microsoft Office. Pour plus d’informations, consultez Configurer un ordinateur pour développer des solutions Bureau.

• Microsoft Word.

Créer un projet de document Word

Créez un document Word que vous utiliserez dans la procédure pas à pas.

Pour créer un projet de document Word

1. Créez un projet de document Word avec le nom EmployeeControls. Créez un document pour la solution. Pour plus d’informations, consultez Guide pratique pour créer des projets Bureau dans Visual Studio.

   Visual Studio ouvre le nouveau document Word dans le concepteur et ajoute le projet EmployeeControls à Explorateur de solutions.

Ajouter des contrôles de contenu au document

Créez une table qui contient trois types différents de contrôles de contenu, où l'utilisateur peut afficher ou modifier les informations sur un employé.

Pour ajouter des contrôles de contenu au document

1. Dans le document Word hébergé dans le concepteur Visual Studio, dans le ruban, choisissez l’onglet Insertion .

2. Dans le groupe Tables , choisissez Table et insérez une table avec 2 colonnes et 3 lignes.

3. Tapez un texte dans la première colonne afin qu'elle se présente de la façon suivante :

   Nom de l’employé
   Date d’embauche
   Titre

4. Dans la deuxième colonne de la table, choisissez la première ligne (en regard du nom de l’employé).

5. Dans le ruban, choisissez l’onglet Développeur .

   Remarque

   Si l'onglet Développeur n'est pas visible, vous devez tout d'abord l'afficher. Pour plus d’informations, consultez Guide pratique pour afficher l’onglet Développeur du ruban.

6. Dans le groupe Contrôles, choisissez le bouton Texte à ajouter PlainTextContentControl à la première cellule.

7. Dans la deuxième colonne de la table, choisissez la deuxième ligne (en regard de Hire Date).

8. Dans le groupe Contrôles, choisissez le bouton Sélecteur de dates à ajouter DatePickerContentControl à la deuxième cellule.

9. Dans la deuxième colonne du tableau, choisissez la troisième ligne (en regard du titre).

10. Dans le groupe Contrôles, choisissez le bouton Liste déroulante pour ajouter une DropDownListContentControl à la dernière cellule.

    Il s'agit de la totalité de l'interface utilisateur pour ce projet. Si vous exécutez le projet maintenant, vous pouvez entrer un texte dans la première ligne et sélectionner une date dans la deuxième ligne. L'étape suivante consiste à lier les données que vous souhaitez afficher au document d'un fichier XML.

Créer le fichier de données XML

En règle générale, vous obtiendrez les données XML à stocker dans une partie XML personnalisée à partir d'une source externe, telle qu'un fichier ou une base de données. Dans cette procédure pas à pas, vous créez un fichier XML qui contient les données d'employé, accompagnées des éléments que vous souhaitez lier aux contrôles de contenu du document. Pour rendre les données disponibles au moment de l’exécution, incorporez le fichier XML en tant que ressource dans l’assembly de personnalisation.

Pour créer le fichier de données

1. Dans le menu Projet , choisissez Ajouter un nouvel élément.

   La boîte de dialogue Ajouter un nouvel élément s'affiche.

2. Dans le volet Modèles , sélectionnez Fichier XML.

3. Nommez le fichier employees.xml, puis choisissez le bouton Ajouter .

   Le fichier employees.xml s’ouvre dans l’Éditeur de code.

4. Remplacez le contenu du fichier employees.xml par le texte suivant.

   <?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. Dans Explorateur de solutions, choisissez le fichier employees.xml.

6. Dans la fenêtre Propriétés , sélectionnez la propriété Action de génération, puis remplacez la valeur par Ressource incorporée.

   Cette étape incorpore le fichier XML en tant que ressource dans l'assembly lorsque vous générez le projet. Cela vous permet d’accéder au contenu du fichier XML au moment de l’exécution.

Créer un schéma XML

Si vous souhaitez lier un contrôle de contenu à un seul élément unique d'une partie XML personnalisée, vous n'avez pas à utiliser de schéma XML. Toutefois, pour lier le DropDownListContentControl à un ensemble de valeurs, vous devez créer un schéma XML qui valide le fichier de données XML que vous avez créé précédemment. Le schéma XML définit les valeurs possibles pour l'élément title. Vous allez lier le DropDownListContentControl à cet élément plus loin dans cette procédure pas à pas.

Pour créer un schéma XML

1. Dans le menu Projet , choisissez Ajouter un nouvel élément.

   La boîte de dialogue Ajouter un nouvel élément s'affiche.

2. Dans le volet Modèles , sélectionnez Schéma XML.

3. Nommez le schéma employees.xsd et choisissez le bouton Ajouter .

   Le Concepteur de schémas s'ouvre.

4. Dans Explorateur de solutions, ouvrez le menu contextuel pour employees.xsd, puis choisissez Afficher le code.

5. Remplacez le contenu du fichier employees.xsd par le schéma suivant.

   <?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. Dans le menu Fichier , cliquez sur Enregistrer tout pour enregistrer vos modifications dans les fichiers employees.xml et employees.xsd .

Attacher le schéma XML au document

Vous devez joindre le schéma XML au document afin de lier le DropDownListContentControl aux valeurs valides de l'élément title.

Pour attacher le schéma XML au document ( Word 2013 )

1. Activez EmployeeControls.docx dans le concepteur.

2. Dans le ruban, choisissez l’onglet Développeur , puis choisissez le bouton Compléments .

3. Dans la boîte de dialogue Modèles et compléments , choisissez l’onglet Schéma XML, puis cliquez sur le bouton Ajouter un schéma .

4. Accédez au schéma employees.xsd que vous avez créé précédemment, qui se trouve dans le répertoire de votre projet, puis choisissez le bouton Ouvrir .

5. Choisissez le bouton OK dans la boîte de dialogue Schéma Paramètres.

6. Choisissez le bouton OK pour fermer la boîte de dialogue Modèles et compléments .

Pour attacher le schéma XML au document (Word 2010)

1. Activez EmployeeControls.docx dans le concepteur.

2. Dans le ruban, choisissez l’onglet Développeur .

3. Dans le groupe XML , choisissez le bouton Schéma .

4. Dans la boîte de dialogue Modèles et compléments , choisissez l’onglet Schéma XML, puis cliquez sur le bouton Ajouter un schéma .

5. Accédez au schéma employees.xsd que vous avez créé précédemment, qui se trouve dans le répertoire de votre projet, puis choisissez le bouton Ouvrir .

6. Choisissez le bouton OK dans la boîte de dialogue Schéma Paramètres.

7. Choisissez le bouton OK pour fermer la boîte de dialogue Modèles et compléments .

   Le volet Office Structure XML s’ouvre.

8. Fermez le volet Office Structure XML.

Ajouter un composant XML personnalisé au document

Avant de pouvoir lier les contrôles de contenu aux éléments du fichier XML, vous devez ajouter le contenu du fichier XML à une nouvelle partie XML personnalisée du document.

Pour ajouter une partie XML personnalisée au document

1. Dans Explorateur de solutions, ouvrez le menu contextuel de ThisDocument.cs ou ThisDocument.vb, puis choisissez Afficher le code.

2. Ajoutez les déclarations suivantes à la classe ThisDocument. Le code déclare plusieurs objets que vous utiliserez pour ajouter une partie XML personnalisée au document.

   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. Ajoutez la méthode suivante à la classe ThisDocument. Cette méthode obtient le contenu du fichier de données XML qui est incorporé en tant que ressource dans l'assembly, et retourne le contenu sous la forme d'une chaîne 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. Ajoutez la méthode suivante à la classe ThisDocument. La méthode AddCustomXmlPart crée une nouvelle partie XML personnalisée qui contient une chaîne XML qui est passée à la méthode.

   Pour vous assurer que la partie XML personnalisée n'est créée qu'une seule fois, la méthode crée cette partie uniquement si une partie XML personnalisée avec un GUID correspondant n'existe pas dans le document. La première fois que cette méthode est appelée, elle enregistre la valeur de la propriété Id dans la chaîne employeeXMLPartID. La valeur de la chaîne employeeXMLPartID est rendue persistante dans le document, car elle a été déclarée à l'aide de l'attribut 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
   

Lier les contrôles de contenu à des éléments dans la partie XML personnalisée

Liez chaque contrôle de contenu à un élément dans la partie XML personnalisée à l’aide de la propriété XMLMapping de chaque contrôle de contenu.

Pour lier les contrôles de contenu aux éléments de la partie XML personnalisée

1. Ajoutez la méthode suivante à la classe ThisDocument. Cette méthode lie chaque contrôle de contenu à un élément de la partie XML personnalisée et définit le format d'affichage de date de la 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
   

Exécuter votre code lorsque le document est ouvert

Créez la partie XML personnalisée et liez les contrôles personnalisés aux données lorsque le document est ouvert.

Pour exécuter votre code lorsque le document est ouvert

1. Ajoutez le code suivant à la méthode ThisDocument_Startup de la classe ThisDocument. Ce code obtient la chaîne XML du fichier employees.xml , ajoute la chaîne XML à une nouvelle partie XML personnalisée dans le document et lie les contrôles de contenu aux éléments du composant XML personnalisé.

   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
   

Tester le projet

Lorsque vous ouvrez le document, les contrôles de contenu affichent les données à partir des éléments de la partie XML personnalisée. Vous pouvez cliquer sur l’une DropDownListContentControl des trois valeurs valides pour l’élément title , qui sont définies dans le fichier employees.xsd . Si vous modifiez les données dans l'un des contrôles de contenu, les nouvelles valeurs sont enregistrées dans la partie XML personnalisée du document.

Pour tester les contrôles de contenu

1. Appuyez sur F5 pour exécuter le projet.

2. Vérifiez que la table du document ressemble au tableau suivant. Chacune des chaînes de la deuxième colonne est obtenue à partir d'un élément de la partie XML personnalisée du document.

   Colonne	Valeur
   Nom de l’employé	Karina Leal
   Date d’embauche	1er avril 1999
   Titre	Directeur

3. Choisissez la cellule à droite de la cellule Employee Name et tapez un autre nom.

4. Choisissez la cellule à droite de la cellule Hire Date et sélectionnez une date différente dans le sélecteur de dates.

5. Choisissez la cellule à droite de la cellule Titre et sélectionnez un nouvel élément dans la liste déroulante.

6. Enregistrez le document et fermez-le.

7. Dans Explorateur de fichiers, ouvrez le dossier \bin\Debug sous l’emplacement de votre projet.

8. Ouvrez le menu contextuel pour EmployeeControls.docx , puis choisissez Renommer.

9. Nommez le fichier EmployeeControls.docx.zip.

   Le document EmployeeControls.docx est enregistré au format Open XML. En renommant ce document avec l’extension de nom de fichier .zip , vous pouvez examiner le contenu du document. Pour plus d’informations sur Open XML, consultez l’article technique Introducing the Bureau (2007) Open XML file formats.

10. Ouvrez le fichier EmployeeControls.docx.zip .

11. Ouvrez le dossier customXml .

12. Ouvrez le menu contextuel de item2.xml , puis choisissez Ouvrir.

    Ce fichier contient la partie XML personnalisée que vous avez ajoutée au document.

13. Vérifiez que les éléments name, hireDate et title contiennent les nouvelles valeurs que vous avez entrées dans les contrôles de contenu du document.

14. Fermez le fichier item2.xml .

Étapes suivantes

Pour plus d'informations sur l'utilisation des contrôles de contenu, consultez les rubriques suivantes :

• Utilisez tous les contrôles de contenu disponibles pour créer un modèle. Pour plus d’informations, consultez Procédure pas à pas : Créer un modèle à l’aide de contrôles de contenu.

• Modifiez les données des parties XML personnalisées lorsque le document est fermé. La prochaine fois que l'utilisateur ouvre le document, les contrôles de contenu liés aux éléments XML affichent les nouvelles données.

• Utilisez les contrôles de contenu pour protéger les parties d'un document. Pour plus d’informations, consultez Guide pratique pour protéger des parties de documents à l’aide de contrôles de contenu.

Contenu connexe

• Automatiser Word à l’aide d’objets étendus
• Contrôles de contenu
• Guide pratique pour ajouter des contrôles de contenu à des documents Word
• Guide pratique pour protéger des parties de documents à l’aide de contrôles de contenu
• Vue d’ensemble des éléments hôtes et des contrôles hôtes
• Limitations programmatiques des éléments hôtes et des contrôles hôtes
• Ajouter des contrôles à Bureau documents au moment de l’exécution