Contrôles de contenu

  • Article

Les contrôles de contenu vous permettent de concevoir des documents et des modèles qui ont les fonctionnalités suivantes :

À propos 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 s'affiche. 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 les utilisateurs de modifier ou de 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 d'un modèle à des données. Vous pouvez lier des contrôles de contenu aux champs de base de données, aux objets managés dans le .NET Framework, aux é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 VSTO, vous pouvez ajouter des contrôles de contenu à tout document ouvert au moment de l’exécution. Pour plus d’informations, consultez Guide pratique pour ajouter des contrôles de contenu aux documents Word.

Remarque

Vous pouvez utiliser des contrôles de contenu uniquement dans les documents enregistrés au format Open XML. Vous ne pouvez pas utiliser de contrôles de contenu dans des documents enregistrés au format document Word 97-2003 (.doc).

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 obtenir une procédure pas à pas qui montre comment utiliser chacun des contrôles de contenu disponibles, consultez Procédure pas à pas : Créer un modèle à l’aide de contrôles de contenu.

Une galerie de blocs de construction permet aux utilisateurs de sélectionner dans une liste de blocs de construction de documents à 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 commune, un tableau mis en forme ou un en-tête. 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.

Case à cocher

Une case à cocher fournit une interface utilisateur qui représente un état binaire : coché ou décoché.

Contrairement aux autres types de contrôles de contenu, le runtime Visual Studio Tools pour Office ne fournit pas de type spécifique qui représente un contrôle de contenu de zone de case activée. 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, voir Contrôles de contenu de case à cocher dans les projets Word.

Zone de liste modifiable

Une zone de liste modifiable affiche une liste d'éléments que les utilisateurs peuvent sélectionner. Contrairement à une liste déroulante, la zone de liste modifiable 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 permettant de sélectionner une date. Le calendrier s’affiche lorsque l’utilisateur final clique sur la flèche déroulante vers le bas 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.

Une liste déroulante affiche la liste des éléments que les utilisateurs peuvent sélectionner. Contrairement à une zone de liste modifiable, 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 zone 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.

Image

Un contrôle d'image affiche une image. Vous pouvez spécifier l'image au moment du design ou au moment 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 utiliser la propriété Type pour modifier un objet ContentControl de manière à ce qu'il se comporte comme un autre type de contrôle de contenu. 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 modifiable.

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 Guide pratique pour ajouter des contrôles de contenu aux documents Word.

Fonctionnalités courantes 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 :
Obtenir ou définir le texte affiché dans le contrôle Utilisez la propriété Text . Remarque : Les PictureContentControl types et ContentControl les types n’ont pas cette propriété.
Obtenir ou définir 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 PictureContentControl type n’a pas cette propriété.
Obtenir ou définir le titre affiché dans la bordure du contrôle de contenu lorsque l'utilisateur clique sur ce dernier. Utilisez la propriété Title .
Supprimer 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é Temporaire .
Exécuter le code lorsque l'utilisateur clique dans le contrôle de contenu ou lorsque le curseur est déplacé par programmation dans le contrôle de contenu. Gérez l'événement Entering du contrôle.
Exécuter 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écuter 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.

Protéger des 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 de 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 par l'utilisateur. Son seul but est de définir une zone que les utilisateurs ne peuvent pas modifier.

Remarque

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 Guide pratique pour protéger des parties de documents à l’aide de contrôles de contenu.

Lier des 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 apportées. 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 dans des éléments XML (également nommés composants XML personnalisés) incorporés dans le document.

    Pour obtenir une vue d’ensemble des contrôles hôtes de liaison dans Bureau solutions aux données, consultez Lier des données à des contrôles dans Bureau solutions.

Utiliser le 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 lier des données à des contrôles de contenu à l’aide de 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 Guide pratique pour remplir des documents avec des données d’une base de données et comment : remplir des documents à partir 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
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Tableau Byte		 PictureContentControl Aucun

Dans les projets au niveau du document et les projets de complément VSTO, vous pouvez 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. Si vous effectuez cette opération, transmettez la chaîne Text au paramètre propertyName de la Add méthode. 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 Guide pratique pour mettre à jour une source de données avec des données à partir d’un contrôle hôte.

Remarque

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 cliqueront sur le contrôle. Si vous voulez lier ces contrôles à une série de valeurs données à partir de laquelle les utilisateurs peuvent choisir, vous pouvez lier ces contrôles à des éléments d'une partie XML personnalisée.

Lier des 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 composants XML personnalisés, consultez la vue d’ensemble des composants XML personnalisés.

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", String.Empty, null);

Pour obtenir une procédure pas à pas qui montre comment lier des contrôles de contenu à des parties XML personnalisées plus en détail, consultez Procédure pas à pas : Lier des 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 automatiquement activée. Si un utilisateur modifie le texte dans le contrôle, les éléments XML correspondants sont automatiquement mis à jour. 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 de contrôles de contenu suivants à 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 exemple pour vérifier 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 associés à la liaison de données.

Tâche Event
Exécuter le code juste avant que Word mette automatiquement à jour le texte d'un contrôle de contenu lié à une partie XML personnalisée. ContentUpdating
Exécuter 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é). StoreUpdating
Exécuter votre propre code pour valider le contenu du contrôle en fonction de critères personnalisés. Validating
Exécuter le code après que le contenu du contrôle a été validé avec succès. Validated

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 l’heure de conception et le runtime

Un grand 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 d’une solution au niveau du document dans Visual Studio, veillez à modifier les contrôles de contenu uniquement de manière prise en charge au moment de l’exécution.

Si vous modifiez un contrôle de contenu au moment du design d’une manière que le contrôle ne prend pas en charge au moment de l’exécution, le concepteur Visual Studio ne vous avertit pas des 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 du contrôle tout le contenu et toute la mise en forme non pris en charge.

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 définissez la propriété LockContents d’un contrôle de contenu sur True au moment du design, vous pouvez toujours modifier du texte dans le 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 des événements

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érer 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 obtenir une procédure pas à pas qui montre comment lier un contrôle de contenu à une partie XML personnalisée, consultez Procédure pas à pas : Lier des contrôles de contenu à des parties XML personnalisées.

Contrôles de contenu de case à cocher dans les projets Word

Word 2010 a introduit un nouveau type de contrôle de contenu représentant une case à cocher. Toutefois, le runtime Visual Studio Tools pour Office ne fournit pas de type CheckBoxContentControl correspondant que vous pouvez utiliser dans Bureau projets. Pour créer un contrôle de contenu de zone de case activée dans un projet Word 2013 ou Word 2010, utilisez la AddContentControl méthode pour créer un ContentControl objet et transmettez la wdContentControlCheckBox valeur à la méthode pour spécifier un contrôle de contenu de zone de case activée. L'exemple de code suivant montre comment procéder.

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

Contenu connexe