Intégration des propriétés du composant WebPart à SharePoint
Lors de la création de composants WebPart classiques, les propriétés du composant WebPart étaient isolées de SharePoint et leurs valeurs gérées par les utilisateurs finaux. SharePoint Framework vous offre un nouveau jeu de fonctionnalités qui simplifie la gestion des valeurs des propriétés du composant WebPart et les intègre à l’aide de SharePoint Search. Cet article explique comment se servir de ces fonctionnalités lors de la génération de composants WebPart côté client SharePoint Framework.
Important
Le guide suivant s’applique uniquement aux composants WebPart SharePoint Framework côté client situés dans des pages SharePoint modernes. Les fonctionnalités décrites dans cet article ne s’appliquent pas aux composants WebPart SharePoint Framework côté client situés sur des pages classiques.
Propriétés du composant WebPart côté client
Lors de la création de composants WebPart côté client SharePoint Framework, vous pouvez définir des propriétés qui seront configurées par les utilisateurs. En vous servant de propriétés au lieu de valeurs fixes, vous rendrez vos composants WebPart plus flexibles et adaptables à de nombreux scénarios.
Par rapport aux composants WebPart classiques, il existe certaines différences dans la façon dont SharePoint Framework gère les propriétés des composants WebPart. Le schéma ci-dessous illustre les variations des valeurs de propriétés des composants WebPart dans les différentes couches de SharePoint.

Avant d’accepter les valeurs de propriétés du composant WebPart fournies par l’utilisateur final, vous devez toujours les valider. Ainsi, vous pourrez non seulement vous assurer que vos composants WebPart sont conviviaux, mais vous éviterez aussi de stocker des données non valides dans la configuration du composant WebPart.
En outre, vous devez garder à l’esprit que SharePoint Framework ne prend pas en charge la personnalisation et que tous les utilisateurs voient la même configuration du composant WebPart.
Spécification du type de valeur des composants WebPart
Dans les composants WebPart SharePoint classiques, les valeurs de propriétés du composant WebPart étaient isolées de SharePoint. Si vous aviez une propriété de composant WebPart avec l’URL d’un fichier stocké dans SharePoint, vous deviez vérifier manuellement que cette URL était valide et pointait vers le bon document, car ce dernier aurait pu avoir été déplacé ou renommé. En outre, si vous aviez permis aux utilisateurs d’entrer du texte à afficher dans le composant WebPart, ce texte n’était pas indexé par SharePoint Search.
Lors de la création de composants WebPart, SharePoint Framework vous permet de spécifier le type de valeur détenue par la propriété du composant WebPart. Cette configuration détermine la manière dont SharePoint gère la valeur. Selon la configuration spécifiée, SharePoint peut inclure la valeur d’une propriété donnée dans l’index de recherche, supprimer les HTML potentiellement dangereux, et même mettre à jour des liens vers des documents stockés dans SharePoint au cas où un fichier serait déplacé ou renommé.
Pour spécifier la configuration des propriétés de vos composants WebPart, dans la classe des composants WebPart, remplacez le getter propertiesMetadata :
import {
BaseClientSideWebPart,
IWebPartPropertiesMetadata
} from '@microsoft/sp-webpart-base';
import {
IPropertyPaneConfiguration,
PropertyPaneTextField,
} from '@microsoft/sp-property-base';
// ...
export default class ArticleLinkWebPart extends BaseClientSideWebPart<IArticleLinkWebPartProps> {
// ...
protected get propertiesMetadata(): IWebPartPropertiesMetadata {
return {
'title': { isSearchablePlainText: true },
'intro': { isHtmlString: true },
'image': { isImageSource: true },
'url': { isLink: true }
};
}
// ...
}
La méthode getterpropertiesMetadata renvoie un objet où la propriété est une chaîne indiquant le nom de la propriété du composant WebPart et la valeur est un objet spécifiant comment SharePoint doit gérer cette propriété en particulier.
Lors de la substitution de la méthode getterpropertiesMetadata, vous n’avez pas à indiquer toutes les propriétés du composant WebPart. Par défaut, les valeurs de propriétés du composant WebPart ne sont pas traitées par SharePoint ; vous devez inclure uniquement les propriétés que vous souhaitez voir traitées.
Vous trouverez ci-dessous la liste des valeurs possibles pouvant être définies dans les métadonnées des propriétés, et leur incidence sur la façon dont la valeur de la propriété du composant WebPart est traitée par SharePoint.
| Valeur des métadonnées | Utilisable dans une recherche | Correction de lien | Suppression d’HTML potentiellement dangereux |
|---|---|---|---|
| Aucun (paramètre par défaut) | Non | Non | Non |
isSearchablePlainText |
Oui | Non | Non |
isHtmlString |
Oui | oui | oui |
isImageSource |
oui | Oui | Non |
isLink |
Oui | Oui | Non |
Important
Lorsque vous définissez la configuration des propriétés de votre composant WebPart, vous devez utiliser une seule des propriétés ci-dessus pour chaque propriété du composant WebPart. Définir plusieurs propriétés risque d’entraîner des résultats indésirables et est donc déconseillé.
Par défaut, la valeur d’une propriété de composant WebPart n’est pas indexée par SharePoint Search et n’est aucunement traitée par SharePoint. Elle est incluse dans le composant WebPart exactement telle qu’elle a été entrée par l’utilisateur ayant configuré le composant WebPart.
Si vous spécifiez la propriété du composant WebPart en tant que isSearchablePlainText, elle est incluse dans l’index de recherche en texte intégral. Chaque fois que les utilisateurs recherchent des mots clés inclus dans la valeur de cette propriété, SharePoint Search les renvoie à la page comportant le composant WebPart dans les résultats de recherche. Si la valeur contient un lien vers un document stocké dans SharePoint, ce lien ne sera pas mis à jour si le document référencé est déplacé ou renommé. En outre, tout code HTML entré par les utilisateurs reste intact. Lorsque vous travaillez sur la valeur d’une propriété de ce type, vous devez la traiter comme un texte brut et échapper le code HTML qui a pu être entré par les utilisateurs avant de l’afficher sur la page afin d’éviter l’injection de script.
Lorsqu’une propriété de composant WebPart est définie sur isHtmlString, SharePoint commence par supprimer tout code HTML potentiellement dangereux, comme les indicateurs <script>, de la valeur de propriété. Le code HTML restant peut être considéré comme fiable pour le rendu de la page. Si la valeur contient une quelconque URL pointant vers des fichiers stockés dans SharePoint, dès qu’un de ces fichiers est renommé ou déplacé, SharePoint met automatiquement à jour l’URL stockée dans la propriété du composant WebPart. Cela simplifie considérablement la gestion des URL sur tous les composants WebPart et sur les pages de votre client. Les propriétés HTML du composant WebPart sont également consultables afin de permettre aux utilisateurs de rechercher des mots clés inclus dans la valeur de propriété.
Les types de valeurs des propriétés isImageSource et isLinksont destinés à être utilisés pour les propriétés de composant WebPart qui n’incluent rien d’autre qu’un lien vers une image ou un fichier stocké dans SharePoint. Dans ces deux cas, SharePoint Search inclut le contenu dans l’index en texte intégral et met à jour l’URL spécifiée au cas où le fichier référencé serait renommé ou déplacé. En outre, les sources de l’image peuvent bénéficier d’un traitement supplémentaire pour un téléchargement plus rapide. Si la page contient une image de titre, et si cette image fait partie des 5 premières images de la page ou si elle se trouve dans les deux premières lignes de la page, l’image est préchargée.