Valider les valeurs des propriétés de composant WebPart

Lorsque vous utilisez des composants WebPart, côté client SharePoint Framework, les utilisateurs peuvent les configurer de manière à ce qu’ils répondent à leurs besoins via leurs propriétés. En validant les valeurs de configuration fournies, vous pouvez faciliter la configuration du composant WebPart pour les utilisateurs et améliorer la convivialité générale de votre composant WebPart.

Notes

Avant de suivre la procédure décrite dans cet article, n’oubliez pas de configurer votre environnement de développement pour générer des solutions SharePoint Framework.

Création d’un projet de composant WebPart

  1. Commencez par créer un dossier pour votre projet :

    md react-listinfo
    
  2. Accédez au dossier du projet :

    cd react-listinfo
    
  3. Dans le dossier du projet, exécutez le générateur SharePoint Framework Yeoman pour structurer un nouveau projet :

    yo @microsoft/sharepoint
    
  4. Lorsque vous y êtes invité, entrez les valeurs suivantes (sélectionnez l’option par défaut pour toutes les invites qui ne sont pas mentionnées ci-dessous) :

    • Quel est le nom de votre solution ? react-listinfo
    • Où voulez-vous placer les fichiers ? : utilisez le dossier actuel
    • Quel est le nom de votre composant WebPart ? : List info
    • Quelle est la description de votre composant WebPart ? : Affiche des informations sur la liste sélectionnée
    • Quelle infrastructure voulez-vous utiliser ? : Aucune infrastructure JavaScript
  5. Ouvrez votre dossier de projet dans votre éditeur de code. Cet article utilise Visual Studio Code dans les étapes et les captures d’écran, mais vous pouvez utiliser n’importe quel éditeur de votre choix.

Options de validation des propriétés du composant WebPart

SharePoint Framework offre aux développeurs deux façons de valider les valeurs de propriétés du composant WebPart. Vous pouvez valider la valeur directement, à l’intérieur du code d’un composant WebPart, ou appeler une API externe pour y effectuer la validation.

La validation directe des valeurs est utile pour effectuer des validations simples, par exemple pour la longueur minimale/maximale, les propriétés requises ou la reconnaissance des modèles simples, comme un code postal. Quand la validation est fondée sur une logique métier, par exemple pour la vérification d’un numéro de sécurité sociale ou de l’appartenance à un groupe de sécurité, l’appel à une API externe est une meilleure approche.

Pour valider la valeur d’une propriété de composant WebPart, vous devez mettre en œuvre le gestionnaire d’événements de l’événement onGetErrorMessage de cette propriété particulière. Pour une validation directe, le gestionnaire d’événements renvoie une chaîne présentant l’erreur de validation ou, si la valeur fournie est valide, une chaîne vide.

Pour la validation à l’aide d’API distantes, le gestionnaire d’événements renvoie une promesse de chaîne. Si la valeur fournie n’est pas valide, la promesse est résolue de manière à afficher le message d’erreur. Si la valeur fournie est valide, la promesse est résolue en une chaîne vide.

Valider les valeurs des propriétés de composant WebPart directement dans le code

À cette étape, vous vérifiez que la propriété de description du composant WebPart est spécifiée et que sa valeur ne dépasse pas 40 caractères. Pour cela, vous utilisez le processus de validation directe.

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/ListInfoWebPart.ts. Dans la classe ListInfoWebPart, ajoutez la méthode validateDescription() avec le code suivant :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      private validateDescription(value: string): string {
        if (value === null ||
          value.trim().length === 0) {
          return 'Provide a description';
        }
    
        if (value.length > 40) {
          return 'Description should not be longer than 40 characters';
        }
    
        return '';
      }
    }
    

    La méthode validateDescription() vérifie si la description est fournie et si elle ne dépasse pas 40 caractères. Si la description fournie n’est pas valide, la méthode renvoie un message d’erreur correspondant à l’erreur de validation. Si la valeur fournie est correcte, elle renvoie une chaîne vide.

  2. Associez la méthode validateDescription() à la propriété du composant WebPart description. Dans la classe ListInfoWebPart, remplacez l’implémentation de la méthode getPropertyPaneConfiguration() par :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
        return {
          pages: [
            {
              header: {
                description: strings.PropertyPaneDescription
              },
              groups: [
                {
                  groupName: strings.BasicGroupName,
                  groupFields: [
                    PropertyPaneTextField('description', {
                      label: strings.DescriptionFieldLabel,
                      onGetErrorMessage: this.validateDescription.bind(this)
                    })
                  ]
                }
              ]
            }
          ]
        };
      }
    
      // ...
    }
    

    Vous avez étendu la définition du composant WebPart description en définissant la méthode validateDescription() comme gestionnaire d’événements pour l’événement onGetErrorMessage.

  3. Exécutez la commande suivante pour afficher le résultat de la validation :

    gulp serve
    
  4. Dans le workbench, ajoutez le composant WebPart au canevas, puis ouvrez ses propriétés. Si vous supprimez la description, la première erreur de validation doit s’afficher.

    Erreur de validation affichée sur une propriété obligatoire sans valeur spécifiée

  5. Fournissez une valeur de plus de 40 caractères. Vous devriez voir une autre erreur de validation sous le champ de texte.

    Erreur de validation affichée lorsque la valeur fournie est plus longue qu’autorisé

  6. Notez que lors de la fourniture d’une valeur non valide, le composant WebPart s’affiche avec la dernière valeur valide. En outre, en mode de volet de propriétés non réactif, si l’une des propriétés du composant WebPart n’est pas valide, le bouton Appliquer est désactivé, ce qui empêche l’utilisateur d’appliquer la configuration non valide.

    Bouton Apply désactivé lorsqu’une propriété de composant WebPart a une valeur non valide

  7. Arrêtez le serveur web local en appuyant sur Ctrl+C dans la console.

Valider les valeurs de propriétés de composant WebPart en utilisant des API à distance

Dans certains cas de figure, la validation des valeurs de propriétés de composant WebPart peut être plus complexe et requérir une logique métier spécifique. Dans ce cas, il peut être plus efficace pour vous de vérifier les valeurs à l’aide d’une API existante plutôt que d’implémenter la logique métier dans le composant WebPart, avec les opérations de maintenance que cela implique.

Dans cette étape, vous implémentez une logique de validation qui vérifie si la liste portant le nom spécifié dans les propriétés du composant WebPart existe sur le site SharePoint sur lequel vous travaillez.

Ajouter la propriété de composant listName

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/ListInfoWebPart.manifest.json. Dans la propriété properties, ajoutez une nouvelle propriété nommée listName dont la valeur par défaut est une chaîne vide :

    {
      "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
      "id": "1ec8f92d-ea55-4584-bf50-bac435c916bf",
      "alias": "ListInfoWebPart",
      "componentType": "WebPart",
    
      "version": "*",
      "manifestVersion": 2,
    
      "requiresCustomScript": false,
    
      "preconfiguredEntries": [{
        "groupId": "1ec8f92d-ea55-4584-bf50-bac435c916bf",
        "group": { "default": "Under Development" },
        "title": { "default": "List info" },
        "description": { "default": "Shows information about the selected list" },
        "officeFabricIconFontName": "Page",
        "properties": {
          "description": "List info",
          "listName": ""
        }
      }]
    }
    
  2. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/IListInfoWebPart.ts, puis développez la définition de l’interface avec la propriété listName de type chaîne.

    export interface IListInfoWebPartProps {
      description: string;
      listName: string;
    }
    
  3. Pour terminer l’ajout de la nouvelle propriété de composant WebPart, dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/ListInfoWebPart.ts et définissez l’implémentation de la méthode getPropertyPaneConfiguration() de la façon suivante :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
        return {
          pages: [
            {
              header: {
                description: strings.PropertyPaneDescription
              },
              groups: [
                {
                  groupName: strings.BasicGroupName,
                  groupFields: [
                    PropertyPaneTextField('description', {
                      label: strings.DescriptionFieldLabel,
                      onGetErrorMessage: this.validateDescription.bind(this)
                    }),
                    PropertyPaneTextField('listName', {
                      label: strings.ListNameFieldLabel
                    })
                  ]
                }
              ]
            }
          ]
        };
      }
    
      // ...
    }
    
  4. Ajoutez la chaîne de ressources ListNameFieldLabel manquante en modifiant le code du fichier ./src/webparts/listInfo/loc/mystrings.d.ts de la façon suivante :

    declare interface IListInfoWebPartStrings {
      PropertyPaneDescription: string;
      BasicGroupName: string;
      DescriptionFieldLabel: string;
      ListNameFieldLabel: string;
    }
    
    declare module 'listInfoStrings' {
      const strings: IListInfoWebPartStrings;
      export = strings;
    }
    
  5. Modifiez le code du fichier ./src/webparts/listInfo/loc/en-us.js de la façon suivante :

    define([], function() {
      return {
        "PropertyPaneDescription": "Description",
        "BasicGroupName": "Group Name",
        "DescriptionFieldLabel": "Description Field",
        "ListNameFieldLabel": "List name"
      }
    });
    
  6. Exécutez la commande suivante pour vérifier que le projet est en cours d’exécution et que la propriété de nom de liste nouvellement ajoutée est affichée dans le volet de propriétés du composant WebPart :

    gulp serve
    

    Propriété de nom de liste affichée dans le volet de propriétés du composant WebPart

  7. Arrêtez le serveur web local en appuyant sur Ctrl+C dans la console.

Valider le nom de la liste à l’aide de l’API REST SharePoint

À cette étape, vous allez valider le nom de la liste fournie et vérifier s’il correspond à une liste existante sur le site SharePoint sur lequel vous travaillez.

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/ListInfoWebPart.ts et ajoutez les références suivantes :

    import { SPHttpClient, SPHttpClientResponse } from '@microsoft/sp-http';
    import { escape } from '@microsoft/sp-lodash-subset';
    
  2. Dans la classe ListInfoWebPart, ajoutez la méthode validateListName() avec le code suivant :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      private async validateListName(value: string): Promise<string> {
        if (value === null || value.length === 0) {
          return "Provide the list name";
        }
    
        try {
          let response = await this.context.spHttpClient.get(
            this.context.pageContext.web.absoluteUrl +
              `/_api/web/lists/getByTitle('${escape(value)}')?$select=Id`,
            SPHttpClient.configurations.v1
          );
    
          if (response.ok) {
            return "";
          } else if (response.status === 404) {
            return `List '${escape(value)}' doesn't exist in the current site`;
          } else {
            return `Error: ${response.statusText}. Please try again`;
          }
        } catch (error) {
          return error.message;
        }
      }
    
      // ...
    }
    

    Tout d’abord, la méthode validateListName() vérifie si un nom de liste est présent. Si ce n’est pas le cas, elle résout la promesse en une erreur de validation appropriée. Si l’utilisateur a fourni un nom de liste, la méthode validateListName() utilise SPHttpClient pour appeler l’API REST SharePoint et vérifier s’il existe une liste portant le nom spécifié.

    Si la liste avec le nom spécifié existe sur le site, la réponse renvoie le code de statut 200 (OK) et la méthode validateListName() résout la promesse en une chaîne vide, ce qui confirme que la valeur fournie représente une liste valide.

    Si la liste avec le nom spécifié n’existe pas, la réponse renvoie un autre code. En règle générale, il s’agit du code 404 (Introuvable), mais la réponse peut renvoyer un autre code si la demande a échoué d’une autre manière. Dans les deux cas, la méthode validateListName() envoie le message d’erreur approprié à l’utilisateur.

    Une fois la méthode de validation de nom de liste définie, l’étape suivante consiste à la configurer en tant que gestionnaire de validation pour la propriété listName du composant WebPart.

  3. Dans la classe ListInfoWebPart, remplacez le code de la méthode getPropertyPaneConfiguration par :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
        return {
          pages: [
            {
              header: {
                description: strings.PropertyPaneDescription
              },
              groups: [
                {
                  groupName: strings.BasicGroupName,
                  groupFields: [
                    PropertyPaneTextField('description', {
                      label: strings.DescriptionFieldLabel,
                      onGetErrorMessage: this.validateDescription.bind(this)
                    }),
                    PropertyPaneTextField('listName', {
                      label: strings.ListNameFieldLabel,
                      onGetErrorMessage: this.validateListName.bind(this)
                    })
                  ]
                }
              ]
            }
          ]
        };
      }
    
      // ...
    }
    
  4. Exécutez la commande suivante pour afficher le résultat de la validation :

    gulp serve --nobrowser
    

    Étant donné que la méthode de validation de nom de liste communique avec l’API REST SharePoint, vous devez tester le composant WebPart dans la version hébergée de SharePoint Workbench.

  5. Ajoutez le composant WebPart au canevas, puis ouvrez ses propriétés. Étant donné que vous n’avez pas spécifié de valeur par défaut pour le nom de liste, qui est une propriété obligatoire, une erreur de validation s’affiche.

    Erreur de validation affichée sur une propriété obligatoire sans valeur spécifiée

    Si vous indiquez un nom d’une liste qui n’existe pas, le composant WebPart affiche une erreur de validation indiquant que la liste que vous avez spécifiée n’existe pas dans le site actuel.

    Erreur de validation affichée après avoir fourni un nom de liste qui n’existe pas sur le site

    Si vous spécifiez le nom d’une liste existante, l’erreur de validation disparaît.

    Aucune erreur de validation affichée pour un nom de liste valide

Optimiser la validation à l’aide d’API à distance

Lors de la validation des propriétés du composant WebPart à l’aide d’API distantes, l’infrastructure SharePoint surveille les modifications apportées dans les contrôles du volet de propriétés et envoie des valeurs mises à jour pour la validation au gestionnaire de validation spécifié. Par défaut, SharePoint Framework attend 200 ms avant le déclenchement de la procédure de validation. Si l’utilisateur n’a pas modifié la valeur particulière au bout de 200 ms, SharePoint Framework démarre le processus de validation. Lorsque le gestionnaire de validation utilise une API à distance, chaque fois que le processus de validation démarre, cette méthode émet une requête web auprès de l’API pour valider la valeur spécifiée. Si les utilisateurs ne tapent pas assez rapidement, des valeurs partielles risquent d’être envoyées à la validation, ce qui surcharge inutilement le réseau et l’API. Dans ce cas, vous devez sans doute augmenter le délai de validation.

Outils réseau de Microsoft Edge présentant des requêtes web où un nom de liste partiel est transmis pour validation

Vous pouvez configurer le délai de validation pour chaque propriété séparément, selon le type de valeur que les utilisateurs doivent fournir.

Augmenter le délai de validation de la propriété listName

  1. Dans l’éditeur de code, ouvrez le fichier ./src/webparts/listInfo/ListInfoWebPart.ts. Remplacez le code de la méthode getPropertyPaneConfiguration() par :

    export default class ListInfoWebPart extends BaseClientSideWebPart<IListInfoWebPartProps> {
      // ...
    
      protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
        return {
          pages: [
            {
              header: {
                description: strings.PropertyPaneDescription
              },
              groups: [
                {
                  groupName: strings.BasicGroupName,
                  groupFields: [
                    PropertyPaneTextField('description', {
                      label: strings.DescriptionFieldLabel,
                      onGetErrorMessage: this.validateDescription.bind(this)
                    }),
                    PropertyPaneTextField('listName', {
                      label: strings.ListNameFieldLabel,
                      onGetErrorMessage: this.validateListName.bind(this),
                      deferredValidationTime: 500
                    })
                  ]
                }
              ]
            }
          ]
        };
      }
    
      // ...
    }
    
    
  2. La propriété deferredValidationTimedeferredValidationTime spécifie le temps en millisecondes pendant lequel SharePoint Framework doit attendre avant de démarrer le processus de validation.

  3. Exécutez la commande suivante pour vérifier que le délai appliqué fonctionne comme prévu :

    gulp serve --nobrowser
    
  4. Une fois le délai validé, arrêtez le serveur web local en appuyant sur CTRL+C dans la console.