Procédure : créer une classe de champ personnalisé

Article
09/24/2014

Dernière modification : mercredi 15 septembre 2010

S’applique à : SharePoint Foundation 2010

Pour créer une classe de type champ personnalisé, vous devez dériver une classe soit de la classe SPField, soit de l'une des classes répertoriées dans le tableau ci-dessous, qui dérivent toutes de la classe SPField.

Notes

Il existe d’autres classes de type champ (classes dont les noms respectent le modèle SPField*), mais elles sont traitées de manière spéciale par Microsoft SharePoint Foundation et la dérivation de nouvelles classes à partir de celles-ci n’est pas prise en charge.

Nous vous recommandons d'utiliser la convention d'affectation de nom suivante lorsque vous créez des classes de champ personnalisé qui dérivent, directement ou indirectement, de la classe SPField :

nom_type_champField

TargetDateField et RegularExpressionField sont des exemples de classes correctement nommées. (Les classes dérivées de SPField livrées avec SharePoint Foundation ont été créées avant l’application de cette convention d’affectation de nom et utilisent le modèle SPFieldnom_type_champ, comme SPFieldDateTime.)

Classes de champ personnalisé dérivables des membres de la classe SPField suivants

Les classes de type de champ personnalisé qui n'héritent pas directement de la classe SPField doivent dériver de l'une des classes suivantes.

Classe	Description
SPFieldBoolean	Représente un type de champ Boolean.
SPFieldChoice	Représente un type de champ choix.
SPFieldCurrency	Représente un type de champ monétaire.
SPFieldDateTime	Représente un type de champ date et heure.
SPFieldLookup	Représente un champ de recherche. La valeur du champ d'un objet SPFieldLookup est contenue dans un objet SPFieldLookupValue.
SPFieldMultiChoice	Représente un type de champ choix multiple. La valeur du champ d'un objet SPFieldMultiChoice est contenue dans un objet SPFieldMultiChoiceValue.
SPFieldMultiColumn	Représente un type de champ multicolonne. La valeur du champ d'un objet SPFieldMultiColumn est contenue dans un objet SPFieldMultiColumnValue.
SPFieldMultiLineText	Représente un type de champ texte multiligne.
SPFieldNumber	Représente un type de champ numérique.
SPFieldRatingScale	Représente un type de champ d'évaluation. La valeur du champ d'un objet SPFieldRatingScale est contenue dans un objet SPFieldRatingScaleValue.
SPFieldText	Représente un type de champ texte sur une seule ligne.
SPFieldUrl	Représente un type de champ URL. La valeur du champ d'un objet SPFieldUrl est contenue dans un objet SPFieldUrlValue.
SPFieldUser	Représente un utilisateur de SharePoint Foundation.

Notes

Pour plus d'informations sur la création de classes de valeur de champ personnalisé, voir Procédure : créer une classe de valeurs de champs personnalisée.

Spécification du comportement du champ personnalisé

Après avoir choisi la classe de champ à partir de laquelle vous souhaitez dériver votre type de champ personnalisé, vous pouvez sélectionner les membres de cette classe que vous voulez remplacer. Étant donné que la plupart des propriétés et comportements qui font qu'un type de champ est unique sont contenus dans sa classe, une grande part de la sémantique de remplacement consiste simplement à choisir la classe dérivée de SPField que votre nouvelle implémentation remplacera.

Par exemple, la classe SPField contient les membres suivants dont l'implémentation est remplaçable, si nécessaire, pour développer des types de champs personnalisés :

Notes

Pour la plupart des membres répertoriés dans cette section, l'implémentation par défaut de la classe SPField n'est pas destinée à une tâche utile ; par exemple, GetFieldValue retourne simplement ce qui lui a été passé, et GetValidatedString appelle simplement la méthode ToString de la classe de valeur (qui ne contient aucune logique de validation). Pour cette raison, si votre classe de type de champ personnalisé dérive directement de SPField, vous devez fournir les substitutions des membres qui vous sont nécessaires pour l'usage prévu.

Membres de la classe SPField qui nécessitent fréquemment une substitution

Membres de SPField Class	Description
FieldRenderingControl	Retourne un contrôle pouvant être utilisé pour générer le champ dans des formulaires Affichage, Modifier et Nouveau et les pages qui utilisent des contrôles de champ. Un objet instanciant un contrôle de rendu contient, dans sa propriété Field, une référence vers l’objet champ qu’il génère. Comme ces références réciproques le suggèrent, les deux objets sont partenaires. L’objet dérivé de SPField gère l’interaction avec la base de données de contenu, tandis que le contrôle de rendu dérivé de BaseFieldControl gère l’interaction avec les utilisateurs et le rendu du champ dans l’interface utilisateur. Cependant, il n’est pas nécessaire de générer un champ personnalisé avec un contrôle de rendu : il peut également être généré avec un RenderPattern défini dans une définition de champ, auquel cas la propriété FieldRenderingControl peut être null. Le modèle le plus courant consiste à utiliser un contrôle de rendu pour générer le champ dans les modes Nouveau et Modifier et à utiliser un modèle de rendu pour le générer en mode Affichage. Lorsque vous utilisez un contrôle de rendu, votre classe de champ personnalisé doit substituer l’accesseur get de la propriété FieldRenderingControl par le modèle de code standard suivant : `public override BaseFieldControl FieldRenderingControl { [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)] get { BaseFieldControl fieldControl = new field_type_nameFieldControl(); fieldControl.FieldName = this.InternalName; return fieldControl; } }` `Public Overrides ReadOnly Property FieldRenderingControl() As BaseFieldControl <SharePointPermission(SecurityAction.LinkDemand, ObjectModel := True)> _ Get Dim fieldControl As BaseFieldControl = New field_type_nameFieldControl() fieldControl.FieldName = Me.InternalName Return fieldControl End Get End Property` L’attribut d’autorisation garantit que seul le code disposant de l’autorisation d’utiliser le modèle objet SharePoint Foundation peut lire la propriété. La ligne attribuant le nom interne de l’objet champ à la propriété FieldName définit également la propriété Field de l’objet champ. Cela garantit que votre nom_type_champFieldControl sait quel objet il génère.
FieldRenderingMobileControl	Retourne un contrôle qui peut être utilisé pour générer le champ dans les formulaires Affichage, Modification et Nouveau dans les applications mobiles.
GetFieldValueForEdit	Retourne la valeur du champ à générer en mode édition. Cette méthode est utilisée pour les formulaires Modification et Nouveau.
GetValidatedString	En cas de substitution dans une classe dérivée, retourne la valeur du champ validé. Substituez cette méthode pour une validation et une logique de sérialisation des données personnalisées. (La méthode de base ne fournit aucune logique de validation, comme de nombreuses classes SharePoint Foundation qui en dérivent.) Cette méthode peut à son tour utiliser la méthode ToString de l’objet valeur du champ pour convertir celui-ci en chaîne. La substitution par défaut doit effectuer les opérations suivantes : Lever SPFieldValidationException lorsque la valeur que l’utilisateur a donnée pour le champ n’est pas valide, ou si la valeur est null alors que le champ est requis. Cette exception est interceptée par SharePoint Foundation si l’utilisateur tente d’enregistrer une valeur non valide. Par exemple, le nouveau formulaire Nouveau ouvert et la propriété Message de l’exception est utilisée pour placer un message d’erreur en regard du champ non valide. Appeler la base GetValidatedString si et seulement si la valeur réussit votre validation personnalisée. Voir Validation des données du champ personnalisé pour plus d'informations et un exemple de substitution de GetValidatedString
OnAdded	Substituer pour spécifier la logique de type de champ personnalisé après l'ajout d'un champ à une liste.
OnUpdated	Substituer pour spécifier la logique de type de champ personnalisé après la mise à jour d'un champ.
OnDeleting	Substituer pour spécifier la logique de type de champ personnalisé avant la suppression d'un champ d'une liste.

Membres de la classe SPField fréquemment substitués lorsqu'un type de données personnalisé complexe est utilisé

Il existe également plusieurs membres de la classe SPField que vous êtes susceptible de substituer lorsque le type de champ requiert un type de données personnalisé complexe différent de celui du champ parent. Vous définissez ces types de données personnalisés avec les classes de valeur de champ personnalisé. Pour plus d’informations, voir Procédure : créer une classe de valeurs de champs personnalisée. (Vous devrez peut-être aussi substituer ces membres dans d’autres cas, même si vous ne créez pas de types de données personnalisés.)

Membres de la classe SPField	Description
DefaultValue	Retourne, sous la forme d'une chaîne, une valeur par défaut qui peut être utilisée pour le champ lorsqu'un élément de liste particulier n'a aucune valeur dans le champ.
DefaultValueTyped	Retourne une valeur par défaut qui peut être utilisée pour le champ lorsqu'un élément de liste particulier n'a aucune valeur dans le champ.
FieldValueType	Retourne le type de la valeur du champ.
GetFieldValue	Retourne la valeur du champ en tant qu'objet.
GetFieldValueAsText	Retourne la valeur des données du champ sous la forme d'une chaîne.
GetFieldValueAsHtml	Retourne la valeur des données du champ sous la forme d’une chaîne au format HTML. Cette valeur au format HTML est le plus souvent utilisée pour restituer la valeur du champ directement sur une page. Par exemple, elle est utilisée sur la page de l’historique de version d’un élément de liste. Toutefois, elle n’est pas utilisée sur le formulaire d’affichage. Le rendu du champ pour le formulaire d’affichage est en général rendu à partir de l’élément Langage CAML (Collaborative Application Markup Language)DisplayPattern dans le fichier fldtype*.xml du type de champ.
GetValidatedString	Voir la remarque dans la section Spécification du comportement du champ personnalisé.
PreviewValueTyped	Retourne une valeur d'aperçu des données du champ, pour un affichage au moment de la création du contrôle du champ en mode d'affichage et d'édition.