Contrôles de contenu
Les contrôles de contenu vous permettent de concevoir des documents et des modèles qui ont les fonctionnalités suivantes :
Une interface utilisateur dont les entrées sont contrôlées comme dans le cas d'un formulaire.
Des restrictions qui empêchent les utilisateurs de modifier les sections protégées du document ou du modèle. Pour plus d'informations, consultez Protection de parties de documents à l'aide de contrôles de contenu.
La liaison à une source de données. Pour plus d'informations, consultez Liaison de données à des contrôles de contenu.
S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document et de niveau application pour Word 2007 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.
.gif "lien vers la vidéo")
Pour une démonstration vidéo connexe, consultez Liaison de données aux contrôles de contenu Word 2007 à l'aide de Visual Studio Tools pour Office System (3.0) (page éventuellement en anglais).
Vue d'ensemble des contrôles de contenu
Les contrôles de contenu fournissent une interface utilisateur optimisée à la fois pour l'entrée d'utilisateur et pour l'impression. Lorsque vous ajoutez un contrôle de contenu à un document, le contrôle est identifié par une bordure, un titre et un texte temporaire qui peut fournir des instructions à l'utilisateur. La bordure et le titre du contrôle n'apparaissent pas dans les versions imprimées du document.
Par exemple, si vous souhaitez que l'utilisateur entre une date dans une section de votre document, vous pouvez ajouter un contrôle du contenu de sélecteur de dates au document. Lorsque les utilisateurs cliquent sur le contrôle, l'interface utilisateur du sélecteur de dates standard apparaît. Vous pouvez également définir les propriétés du contrôle de manière à configurer le calendrier régional affiché et à spécifier le format de date. Lorsque l'utilisateur a choisi une date, l'interface utilisateur du contrôle est masquée et seule la date apparaît si l'utilisateur imprime le document.
Les contrôles de contenu vous aident également à effectuer les opérations suivantes :
Empêcher des utilisateurs de modifier ou supprimer des parties d'un document. Cela peut s'avérer utile si votre document ou modèle contient des informations que les utilisateurs doivent pouvoir lire mais pas modifier, ou si vous souhaitez que les utilisateurs puissent modifier des contrôles de contenu mais pas les supprimer.
Lier des parties d'un document ou modèle à des données. Vous pouvez lier des contrôles de contenu à des champs de base de données, à des objets managés dans le .NET Framework, à des éléments XML stockés dans le document et à d'autres sources de données.
Dans les projets au niveau du document, vous pouvez ajouter des contrôles de contenu à votre document au moment du design ou au moment de l'exécution. Dans les projets au niveau de l'application, vous pouvez ajouter des contrôles de contenu à tout document ouvert au moment de l'exécution. Pour plus d'informations, consultez Comment : ajouter des contrôles de contenu à des documents Word.
Notes
Vous pouvez uniquement utiliser des contrôles de contenu dans les documents enregistrés au format Open XML. Vous ne pouvez pas utiliser de contrôles de contenu dans les documents enregistrés au format de document (.doc) Word 97-2003.
Types de contrôles de contenu
Vous pouvez ajouter neuf types de contrôles de contenu différents à des documents. La plupart des contrôles de contenu disposent d'un type correspondant dans l'espace de noms Microsoft.Office.Tools.Word. Vous avez également la possibilité d'utiliser un ContentControl générique, qui peut représenter l'un des contrôles de contenu disponibles. Pour une procédure pas à pas qui montre comment utiliser chacun des contrôles de contenu disponibles, consultez Procédure pas à pas : création d'un modèle à l'aide de contrôles de contenu.
Galerie de blocs de construction
Une galerie de bloc de construction permet aux utilisateurs de sélectionner dans une liste des blocs de construction de document à insérer dans un document. Un bloc de construction de document est une partie de contenu créée pour être utilisée plusieurs fois, telle qu'une page de garde, une table mise en forme ou un en-tête communs. Pour plus d'informations, consultez le type BuildingBlockGalleryContentControl. Pour plus d'informations sur les blocs de construction, consultez Nouveautés pour les développeurs dans Word 2007.
Check Box
Une case à cocher fournit une interface utilisateur qui représente un état binaire : activé ou désactivé. Ce type de contrôle de contenu est disponible uniquement dans Word 2010.
Contrairement aux autres types de contrôles de contenu, Visual Studio Tools pour Office Runtime ne fournit pas de type spécifique qui représente un contrôle de contenu de case à cocher. En d'autres termes, il n'existe pas de type CheckBoxContentControl. Toutefois, vous pouvez créer un contrôle de contenu de case à cocher en ajoutant par programmation un ContentControl générique à un document. Pour plus d'informations, consultez Contrôles de contenu de case à cocher dans les projets Word 2010.
Combo Box
Une zone de liste déroulante affiche la liste des éléments que les utilisateurs peuvent sélectionner. Contrairement à une liste déroulante, la zone de liste déroulante permet aux utilisateurs d'ajouter leurs propres éléments. Pour plus d'informations, consultez le type ComboBoxContentControl.
Sélecteur de dates
Un sélecteur de dates fournit une interface utilisateur de calendrier pour sélectionner une date. Le calendrier apparaît lorsque l'utilisateur final clique sur la flèche de liste déroulante dans le contrôle. Vous pouvez utiliser des calendriers régionaux et des formats de date différents. Pour plus d'informations, consultez le type DatePickerContentControl.
Liste déroulante
Une liste déroulante affiche la liste des éléments que les utilisateurs peuvent sélectionner. Contrairement à une zone de liste déroulante, la liste déroulante ne permet pas aux utilisateurs d'ajouter ou de modifier des éléments. Pour plus d'informations, consultez le type DropDownListContentControl.
Groupe
Un contrôle de groupe définit une région protégée d'un document que les utilisateurs ne peuvent pas modifier ou supprimer. Un contrôle de groupe peut contenir tous types d'éléments de document : du texte, des tableaux, des graphiques et d'autres contrôles de contenu. Pour plus d'informations, consultez le type GroupContentControl.
Picture
Un contrôle d'image affiche une image. Vous pouvez spécifier l'image au moment du design ou de l'exécution, ou les utilisateurs peuvent cliquer sur ce contrôle pour sélectionner une image à insérer dans le document. Pour plus d'informations, consultez le type PictureContentControl.
Texte enrichi
Un contrôle de texte enrichi contient du texte ou d'autres éléments, comme des tableaux, des images ou d'autres contrôles de contenu. Pour plus d'informations, consultez le type RichTextContentControl.
Texte brut
Un contrôle de texte brut contient du texte. Un contrôle de texte brut ne peut pas contenir d'autres éléments, comme des tableaux, des images ou d'autres contrôles de contenu. En outre, tout le texte d'un contrôle de texte brut a la même mise en forme. Par exemple, si vous mettez en italique un mot d'une phrase contenue dans un contrôle de texte brut, tout le texte à l'intérieur du contrôle est mis en italique. Pour plus d'informations, consultez le type PlainTextContentControl.
Contrôle de contenu générique
Un contrôle de contenu générique est un objet ContentControl qui peut représenter l'un des types de contrôles de contenu disponibles. Vous pouvez modifier un objet ContentControl de manière à ce qu'il se comporte comme un type différent de contrôle de contenu à l'aide de la propriété Type. Par exemple, si vous créez un objet ContentControl qui représente un contrôle de texte brut, vous pouvez le modifier au moment de l'exécution afin qu'il se comporte comme une zone de liste déroulante.
Vous pouvez créer des objets ContentControl uniquement au moment de l'exécution, et pas au moment du design. Pour plus d'informations, consultez Comment : ajouter des contrôles de contenu à des documents Word.
Fonctionnalités communes des contrôles de contenu
La plupart des contrôles de contenu partagent un ensemble de membres que vous pouvez utiliser pour exécuter des tâches courantes. Le tableau suivant décrit quelques-unes des tâches que vous pouvez effectuer à l'aide de ces membres.
Pour cette tâche : |
Procédez comme suit : |
|---|---|
Obtenez ou définissez le texte affiché dans le contrôle. |
Utilisez la propriété Text. .gif "Remarque") Remarque
Les types PictureContentControl et ContentControl n'ont pas cette propriété.
|
Obtenez ou définissez le texte temporaire affiché dans le contrôle jusqu'à ce qu'un utilisateur modifie le contrôle, que le contrôle soit rempli avec les données d'une source de données ou que le contenu du contrôle soit supprimé. |
Utilisez la propriété PlaceholderText. Remarque
Le type PictureContentControl n'a pas cette propriété.
|
Obtenez ou définissez le titre affiché dans la bordure du contrôle de contenu lorsque l'utilisateur clique sur lui. |
Utilisez la propriété Title. |
Supprimez automatiquement le contrôle du document après que l'utilisateur a modifié le contrôle. (Le texte du contrôle reste dans le document.) |
Utilisez la propriété Temporary. |
Exécutez le code lorsque l'utilisateur clique dans le contrôle de contenu ou lorsque le curseur est transféré par programmation vers le contrôle de contenu. |
Gérez l'événement Entering du contrôle. |
Exécutez le code lorsque l'utilisateur clique en dehors du contrôle de contenu ou lorsque le curseur est déplacé par programmation en dehors du contrôle de contenu. |
Gérez l'événement Exiting du contrôle. |
Exécutez le code après que le contrôle de contenu a été ajouté au document à la suite d'une opération de rétablissement ou d'annulation. |
Gérez l'événement Added du contrôle. |
Exécutez le code juste avant que le contrôle de contenu soit supprimé du document. |
Gérez l'événement Deleting du contrôle. |
Protection de parties de documents à l'aide de contrôles de contenu
Lorsque vous protégez une partie d'un document, vous empêchez les utilisateurs de modifier ou de supprimer le contenu dans cette partie du document. Il existe plusieurs manières de protéger des parties d'un document à l'aide de contrôles de contenu.
Si la zone que vous souhaitez protéger se trouve à l'intérieur d'un contrôle de contenu, vous pouvez utiliser les propriétés du contrôle de contenu pour empêcher des utilisateurs de modifier ou supprimer le contrôle :
La propriété LockContents empêche les utilisateurs de modifier le contenu.
La propriété LockContentControl empêche les utilisateurs de supprimer le contrôle.
Si la zone que vous souhaitez protéger ne se trouve pas à l'intérieur d'un contrôle de contenu, ou si vous souhaitez protéger une zone qui contient des contrôles de contenu et d'autres types de contenu, vous pouvez placer la zone entière dans un GroupContentControl. Contrairement à d'autres contrôles de contenu, un GroupContentControl ne fournit aucune interface utilisateur visible à l'utilisateur. Son seul but est de définir une région que les utilisateurs ne peuvent pas modifier.
Notes
Si vous créez un GroupContentControl qui contient des contrôles de contenu incorporés, ces contrôles ne sont pas protégés automatiquement. Vous devez utiliser la propriété LockContents de chaque contrôle incorporé pour empêcher les utilisateurs de modifier leur contenu.
Pour plus d'informations sur l'utilisation de contrôles de contenu pour protéger des parties de documents, consultez Comment : protéger des parties de documents à l'aide de contrôles de contenu.
Liaison de données à des contrôles de contenu
Vous pouvez afficher des données dans des documents en liant un contrôle de contenu à une source de données. Lorsque la source de données est mise à jour, le contrôle de contenu reflète les modifications. Vous pouvez également enregistrer les modifications dans la source de données.
Les contrôles de contenu fournissent les options de liaison des données suivantes :
Vous pouvez lier des contrôles de contenu à des champs de base de données ou des objets managés en utilisant le même modèle de liaison de données que Windows Forms.
Vous pouvez lier des contrôles de contenu à des éléments de fragments XML (également appelés parties XML personnalisées) qui sont incorporés dans le document.
Pour une présentation de la liaison de contrôles hôtes aux données dans les solutions Office, consultez Liaison de données aux contrôles dans les solutions Office.
Utilisation du modèle de liaison de données Windows Forms
La plupart des contrôles de contenu prennent en charge le modèle de liaison de données simple que Windows Forms utilise. La liaison de données simple signifie qu'un contrôle est lié à un élément de données unique, tel qu'une valeur dans une colonne d'une table de données. Pour plus d'informations, consultez Liaison de données et Windows Forms.
Dans les projets au niveau du document, vous pouvez également lier des données à des contrôles de contenu en utilisant la fenêtre Sources de données dans Visual Studio. Pour plus d'informations sur l'ajout de contrôles de contenu liés aux données à des documents, consultez Comment : remplir des documents avec les données d'une base de données et Comment : remplir des documents avec les données d'objets.
Le tableau suivant répertorie les contrôles de contenu que vous pouvez lier à chaque type de données dans la fenêtre Sources de données.
Type de données |
Contrôle de contenu par défaut |
Autres contrôles de contenu qui peuvent être liés à ce type de données |
|---|---|---|
|
Tableau Byte |
Aucun |
Dans les projets au niveau du document et de l'application, vous pouvez également lier par programmation un contrôle de contenu à une source de données en utilisant la méthode Add() de la propriété DataBindings du contrôle. En procédant ainsi, vous passez la chaîne Texte au paramètre propertyName de la méthode Add(). La propriété Text est la propriété de liaison de données par défaut des contrôles de contenu.
Les contrôles de contenu prennent également en charge la liaison de données bidirectionnelle, dans laquelle les modifications apportées au contrôle sont répercutées dans la source de données. Pour plus d'informations, consultez Comment : mettre à jour une source de données avec les données d'un contrôle hôte.
Notes
Les contrôles de contenu ne prennent pas en charge la liaison de données complexe. Si vous liez un DropDownListContentControl ou un ComboBoxContentControl à une source de données à l'aide du modèle de données Windows Forms, les utilisateurs ne verront qu'une seule valeur lorsqu'ils cliquent sur le contrôle. Pour lier ces contrôles à un jeu des valeurs de données à partir duquel les utilisateurs peuvent choisir, vous pouvez lier ces contrôles à des éléments d'une partie XML personnalisée.
Liaison de contrôles de contenu à des parties XML personnalisées
Vous pouvez lier des contrôles de contenu à des éléments dans des parties XML personnalisées qui sont incorporées dans le document. Pour plus d'informations sur les parties XML personnalisées, consultez Vue d'ensemble des parties XML personnalisées.
Pour lier un contrôle de contenu à un élément d'une partie XML personnalisée, utilisez la propriété XMLMapping du contrôle. L'exemple de code suivant montre comment lier un PlainTextContentControl à l'élément Price sous le nœud Product dans une partie XML personnalisée qui a déjà été ajoutée au document.
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);
Pour une procédure pas à pas qui montre comment lier des contrôles de contenu à des parties XML personnalisées dans plus de détails, consultez Procédure pas à pas : liaison de contrôles de contenu à des parties XML personnalisées.
Lorsque vous liez un contrôle de contenu à une partie XML personnalisée, la liaison de données bidirectionnelle est activée automatiquement. Si un utilisateur modifie le texte dans le contrôle, les éléments XML correspondants sont mis à jour automatiquement. De la même façon, si les valeurs d'élément dans les parties XML personnalisées sont modifiées, les contrôles de contenu liés aux éléments XML afficheront les nouvelles données.
Vous pouvez lier les types suivants de contrôles de contenu à des parties XML personnalisées :
Événements de liaison de données pour les contrôles de contenu
Tous les contrôles de contenu fournissent un jeu des événements que vous pouvez gérer afin d'effectuer des tâches liées aux données, par ex. pour valider que le texte d'un contrôle répond à certains critères avant que la source de données soit mise à jour. Le tableau suivant répertorie les événements de contrôle de contenu relatifs à la liaison de données.
Tâche |
Événement |
|---|---|
Exécutez le code juste avant que Word mette automatiquement à jour le texte d'un contrôle de contenu lié à une partie XML personnalisée. |
|
Exécutez le code juste avant que Word mette automatiquement à jour les données dans une partie XML personnalisée liée à un contrôle de contenu (autrement dit, après que le texte du contrôle de contenu a été modifié). |
|
Exécutez votre propre code pour valider le contenu du contrôle selon des critères personnalisés. |
|
Exécutez le code après que le contenu du contrôle a été validé avec succès. |
Limitations des contrôles de contenu
Lorsque vous utilisez des contrôles de contenu dans vos projets Office, vous devez garder à l'esprit les limitations suivantes.
Différences de comportement entre le moment du design et le moment de l'exécution
Nombre des limitations que Microsoft Office Word impose aux contrôles de contenu au moment de l'exécution ne sont pas appliquées au moment du design. Lorsque vous concevez l'interface utilisateur de votre solution au niveau du document dans Visual Studio, veillez à n'apporter aux contrôles de contenu que des modifications susceptibles d'être prises en charge au moment de l'exécution.
Si vous modifiez un contrôle de contenu au moment du design d'une façon que le contrôle ne prend pas en charge au moment de l'exécution, le concepteur Visual Studio ne vous signalera pas les modifications non prises en charge. Toutefois, lorsque vous déboguez ou exécutez le projet, ou si vous enregistrez puis rouvrez le projet, Word affichera un message d'erreur et demandera l'autorisation de réparer le document. Lorsque vous réparez le document, Word supprime tout le contenu et la mise en forme non pris en charge dans le contrôle.
Par exemple, Word ne vous empêche pas d'ajouter un tableau à un PlainTextContentControl au moment du design. Cependant, comme les objets PlainTextContentControl ne peuvent pas contenir de tableaux au moment de l'exécution, Word affichera un message d'erreur à l'ouverture du document.
Notez également que de nombreuses propriétés qui définissent le comportement des contrôles de contenu n'ont aucun effet au moment du design. Par exemple, si vous affectez la valeur True à la propriété LockContents d'un contrôle de contenu au moment du design, vous pouvez encore modifier le texte du contrôle dans le concepteur Visual Studio. Cette propriété empêche seulement les utilisateurs de modifier le contrôle au moment de l'exécution.
Limitations d'événement
Les contrôles de contenu ne fournissent pas un événement déclenché lorsque l'utilisateur modifie le texte ou d'autres éléments dans le contrôle. Par exemple, aucun événement n'est déclenché lorsqu'un utilisateur sélectionne un autre élément dans un DropDownListContentControl ou un ComboBoxContentControl.
Pour déterminer quand un utilisateur modifie le contenu d'un contrôle de contenu, vous pouvez lier le contrôle à une partie XML personnalisée, puis gérez l'événement StoreUpdating. Cet événement est déclenché lorsque l'utilisateur modifie le contenu d'un contrôle lié à une partie XML personnalisée. Pour une procédure pas à pas qui montre comment lier un contrôle de contenu à une partie XML personnalisée, consultez Procédure pas à pas : liaison de contrôles de contenu à des parties XML personnalisées.
Contrôles de contenu de case à cocher dans les projets Word 2010
Word 2010 a introduit un nouveau type de contrôle de contenu représentant une case à cocher. Toutefois, Visual Studio Tools pour Office Runtime ne fournit pas de type CheckBoxContentControl correspondant à utiliser dans les projets Office. Pour créer un contrôle de contenu de case à cocher dans un projet Word 2010, utilisez la méthode AddContentControl de façon à créer un objet Microsoft.Office.Tools.Word.ContentControl et passez la valeur wdContentControlCheckBox à la méthode pour spécifier un contrôle de contenu de case à cocher. L'exemple de code suivant montre comment procéder.
Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)
' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True
' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True
this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 =
this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);
// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;
// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;
Notes
La propriété Checked des objets Microsoft.Office.Tools.Word.ContentControl peut être utilisée directement dans les projets ciblant .NET Framework 4 uniquement. Dans les projets qui ciblent .NET Framework 3.5, vous devez utiliser la propriété InnerObject pour accéder à la propriété Checked de l'objet Microsoft.Office.Interop.Word.ContentControl sous-jacent. Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes.
Voir aussi
Tâches
Comment : ajouter des contrôles de contenu à des documents Word
Procédure pas à pas : création d'un modèle à l'aide de contrôles de contenu
Concepts
Automatisation de Word à l'aide d'objets étendus
Limitations de programmation des éléments hôtes et des contrôles hôtes