Connecter votre composant WebPart côté client à SharePoint (Hello World 2e partie)

Connectez votre composant WebPart à SharePoint pour accéder aux fonctionnalités et aux données de SharePoint et offrir une expérience plus homogène aux utilisateurs finaux. Cet article poursuit le développement du composant WebPart Hello World créé dans l’article précédent, Créer votre premier composant WebPart.

Vous pouvez également suivre cette procédure en regardant la vidéo suivante sur la chaîne YouTube SharePoint PnP :

Exécution de la commande gulp serve

Assurez-vous que la commande gulp serve est en cours d’exécution. Si ce n’est pas le cas, accédez au répertoire du projet helloworld-webpart et exécutez-la à l’aide des commandes suivantes.

cd helloworld-webpart
gulp serve

Accéder au contexte de la page

Le workbench hébergé dans SharePoint permet d’accéder au contexte de page, qui expose les propriétés clés suivantes, telles que :

  • Le titre du site web
  • L’URL absolue du site web
  • L’URL relative au serveur du site web
  • Le nom de connexion de l’utilisateur

Pour obtenir l’accès au contexte de la page

Pour accéder aux informations contextuelles dans votre composant WebPart, vous allez utiliser l’objet suivant dans votre code :

this.context.pageContext
  1. Dans Visual Studio Code, recherchez et ouvrez .\src\webparts\helloWorld\HelloWorldWebPart.ts.

  2. Dans la méthode render(), remplacez le bloc de code innerHTML par ce qui suit :

    this.domElement.innerHTML = `
      <div class="${ styles.helloWorld }">
        <div class="${ styles.container }">
          <div class="${ styles.row }">
            <div class="${ styles.column }">
              <span class="${ styles.title }">Welcome to SharePoint!</span>
              <p class="${ styles.subTitle }">Customize SharePoint experiences using web parts.</p>
              <p class="${ styles.description }">${escape(this.properties.description)}</p>
              <p class="${ styles.description }">${escape(this.properties.test)}</p>
              <p class="${ styles.description }">Loading from ${escape(this.context.pageContext.web.title)}</p>
              <a href="https://aka.ms/spfx" class="${ styles.button }">
                <span class="${ styles.label }">Learn more</span>
              </a>
            </div>
          </div>
        </div>
      </div>`;
    
  3. Vous pouvez remarquer que ${ } est utilisé pour afficher la valeur de la variable dans le bloc de code HTML. Un élément HTML p supplémentaire est utilisé pour afficher this.context.pageContext.web.title.

  4. Enregistrez le fichier. Le gulp sert en cours d’exécution dans votre console détecte cette opération d’enregistrement et :

    • génère et regroupe automatiquement le code mis à jour

    Notes

    Placez la fenêtre de la console et celle de Visual Studio Code côte à côte pour observer Gulp se compiler automatiquement à mesure que vous enregistrez les modifications dans Visual Studio Code.

  5. Accédez au workbench hébergé de votre site SharePoint hébergé. L’URL complète est https://your-sharepoint-site-url/_layouts/workbench.aspx. Actualisez le workbench hébergé pour récupérer les modifications de l’offre groupée de code prédéfinie.

    Maintenant que le contexte de la page est disponible pour le composant WebPart, le titre de votre site SharePoint doit s’afficher dans le composant WebPart.

    Contexte de la page SharePoint dans un site SharePoint

Définition d’un modèle de liste

Vous avez besoin d’un modèle de liste pour commencer à travailler avec les données de liste SharePoint. Pour récupérer les listes, vous avez besoin de deux modèles.

  1. Dans Visual Studio Code, recherchez et ouvrez .\src\webparts\helloWorld\HelloWorldWebPart.ts.

  2. Définissez les interfaces suivantes juste au-dessus de la classe HelloWorldWebPart :

    export interface ISPLists {
      value: ISPList[];
    }
    
    export interface ISPList {
      Title: string;
      Id: string;
    }
    

    L’interface ISPList conserve les informations de liste SharePoint auxquelles vous vous connectez.

Récupération des listes dans une banque de données fictive

Pour tester vos données fictives, vous avez besoin d’un magasin fictif qui retourne des données fictives.

Pour créer une banque de données fictive

  1. Créez un fichier MockHttpClient.ts dans le dossier src\webparts\helloWorld .

  2. Copiez le code suivant dans MockHttpClient.ts :

    import { ISPList } from './HelloWorldWebPart';
    
    export default class MockHttpClient  {
    
      private static _items: ISPList[] = [{ Title: 'Mock List', Id: '1' },
                                          { Title: 'Mock List 2', Id: '2' },
                                          { Title: 'Mock List 3', Id: '3' }];
    
      public static get(): Promise<ISPList[]> {
        return new Promise<ISPList[]>((resolve) => {
          resolve(MockHttpClient._items);
        });
      }
    }
    

    Éléments à noter concernant le code :

    • Il exporte la classe MockHttpClient comme module par défaut afin qu’il puisse être importé dans d’autres fichiers.
    • Il génère le tableau fictif initial ISPList et retourne un tableau d’éléments.
  3. Enregistrez le fichier.

Vous pouvez maintenant utiliser la classe MockHttpClient dans la classe HelloWorldWebPart . Vous devez d’abord importer le module MockHttpClient .

Importer la classe MockHttpClient

  1. Recherchez et ouvrez le fichier HelloWorldWebPart.ts.

  2. Recherchez la ligne import * as strings from 'HelloWorldWebPartStrings'; et ajoutez le code suivant immédiatement après celle-ci :

    import MockHttpClient from './MockHttpClient';
    
  3. Ajoutez la méthode suivante qui simule la récupération de liste à l’intérieur de la classe HelloWorldWebPart.

    private _getMockListData(): Promise<ISPLists> {
      return MockHttpClient.get()
        .then((data: ISPList[]) => {
          var listData: ISPLists = { value: data };
          return listData;
        }) as Promise<ISPLists>;
    }
    
  4. Enregistrez le fichier.

Récupération de listes à partir du site SharePoint

Ensuite, vous devez récupérer des listes à partir du site actuel. Vous allez utiliser les API REST SharePoint pour récupérer les listes du site, qui se trouvent à https://yourtenantprefix.sharepoint.com/_api/web/lists.

SharePoint Framework inclut une classe d’assistance spHttpClient pour exécuter des requêtes API REST par rapport à SharePoint. Elle ajoute des en-têtes par défaut, gère le digest nécessaire pour les écritures et collecte la télémétrie qui permet au service de surveiller les performances d’une application.

Pour utiliser cette classe d’assistance, importez-les à partir du module @microsoft/sp-http.

  1. Faites défiler vers le haut du fichier HelloWorldWebPart.ts.

  2. Recherchez la ligne import MockHttpClient from './MockHttpClient'; et ajoutez le code suivant immédiatement après :

    import {
      SPHttpClient,
      SPHttpClientResponse
    } from '@microsoft/sp-http';
    
  3. Ajoutez la méthode suivante pour récupérer des listes à partir de SharePoint à l’intérieur de la classe HelloWorldWebPart.

    private _getListData(): Promise<ISPLists> {
      return this.context.spHttpClient.get(this.context.pageContext.web.absoluteUrl + `/_api/web/lists?$filter=Hidden eq false`, SPHttpClient.configurations.v1)
        .then((response: SPHttpClientResponse) => {
          return response.json();
        });
    }
    

    La méthode utilise la classe d’assistance spHttpClient et émet une requête HTTP GET. Il utilise l’interface ISPLists et applique également un filtre pour ne pas récupérer les listes masquées.

  4. Enregistrez le fichier.

  5. Revenez à la fenêtre de la console qui exécute gulp serve et vérifiez s’il existe des erreurs. S’il existe des erreurs, Gulp les signale dans la console et vous devez les corriger pour pouvoir continuer.

Ajout de nouveaux styles

SharePoint Framework utilise Sass comme préprocesseur CSS et utilise plus spécifiquement la syntaxe SCSS, qui est entièrement conforme à la syntaxe CSS normale. Sass étend le langage CSS et vous permet d’utiliser des fonctionnalités telles que les variables, les règles imbriquées et les instructions import incorporées pour organiser et créer des feuilles de style efficaces pour vos composants WebPart. SharePoint Framework contient déjà un compilateur SCSS qui convertit vos fichiers Sass en fichiers CSS normaux et fournit également une version typée à utiliser lors des phases de développement.

Pour ajouter de nouveaux styles

  1. Ouvrez HelloWorldWebPart.module.scss. Il s’agit du fichier SCSS dans lequel vous définissez vos styles.

    Par défaut, les styles s’appliquent uniquement à votre composant WebPart. Vous pouvez constater que les styles sont définis sous .helloWorld.

  2. Ajoutez les styles suivants après le style .button, mais toujours à l’intérieur de la section de style .helloWorld principale :

    .list {
      color: #333333;
      font-family: 'Segoe UI Regular WestEuropean', 'Segoe UI', Tahoma, Arial, sans-serif;
      font-size: 14px;
      font-weight: normal;
      box-sizing: border-box;
      margin: 10;
      padding: 10;
      line-height: 50px;
      list-style-type: none;
      box-shadow: 0 4px 4px 0 rgba(0, 0, 0, 0.2), 0 25px 50px 0 rgba(0, 0, 0, 0.1);
    }
    
    .listItem {
      color: #333333;
      vertical-align: center;
      font-family: 'Segoe UI Regular WestEuropean', 'Segoe UI', Tahoma, Arial, sans-serif;
      font-size: 14px;
      font-weight: normal;
      box-sizing: border-box;
      margin: 0;
      padding: 0;
      box-shadow: none;
      *zoom: 1;
      padding: 9px 28px 3px;
      position: relative;
    }
    
  3. Enregistrez le fichier.

    Gulp recompose le code de la console dès que vous enregistrez le fichier. Cela génère les typages correspondants dans le fichier HelloWorldWebPart.module.scss.ts. Une fois ces styles compilés dans TypeScript, vous pouvez les importer et les référencer dans le code de votre composant WebPart.

    Conseil

    Ce fichier est généré dynamiquement lorsque le projet est généré. Il est masqué dans la vue Explorateur de VS Code à l’aide du fichier .vscode/settings.json.

    Vous pouvez voir l’élément suivant dans la méthode render() du composant WebPart :

    <div class="${styles.row}">
    

Rendu des listes d’informations

Ouvrez la classe HelloWorldWebPart .

SharePoint Workbench vous offre la possibilité de tester des composants WebPart dans votre environnement local et à partir d’un site SharePoint. SharePoint Framework facilite cette fonctionnalité en vous aidant à comprendre l’environnement à partir duquel votre composant WebPart s’exécute à l’aide du module EnvironmentType .

Utilisation du module EnvironmentType

  1. Importez les modules Environment et EnvironmentType à partir du fichier groupé @microsoft/sp-core-library. Ajoutez-le à la section import située en haut, comme illustré dans le code suivant :

    import {
      Environment,
      EnvironmentType
    } from '@microsoft/sp-core-library';
    
  2. Ajoutez la méthode privée suivante à l’intérieur de la classe HelloWorldWebPart :

    private _renderList(items: ISPList[]): void {
      let html: string = '';
      items.forEach((item: ISPList) => {
        html += `
      <ul class="${styles.list}">
        <li class="${styles.listItem}">
          <span class="ms-font-l">${item.Title}</span>
        </li>
      </ul>`;
      });
    
      const listContainer: Element = this.domElement.querySelector('#spListContainer');
      listContainer.innerHTML = html;
    }
    

    Cette méthode référence les nouveaux styles CSS ajoutés précédemment à l’aide de la variable styles et est utilisée pour afficher les informations de liste qui seront reçues de l’API REST.

  3. Enregistrez le fichier.

  4. Ajoutez la méthode privée suivante à l’intérieur de la classe HelloWorldWebPart afin d’appeler les méthodes requises pour récupérer les données des listes :

    private _renderListAsync(): void {
      // Local environment
      if (Environment.type === EnvironmentType.Local) {
        this._getMockListData().then((response) => {
          this._renderList(response.value);
        });
      }
      else if (Environment.type == EnvironmentType.SharePoint ||
               Environment.type == EnvironmentType.ClassicSharePoint) {
        this._getListData()
          .then((response) => {
            this._renderList(response.value);
          });
      }
    }
    

    Éléments à noter sur EnvironmentType dans la méthode _renderListAsync() :

    • La propriété Environment.type vous permet de vérifier si vous êtes dans un environnement local ou SharePoint.
    • La méthode correcte est appelée en fonction de l’emplacement d’hébergement de Workbench.
  5. Enregistrez le fichier.

Important

Le code ci-dessus est destiné à fonctionner uniquement lorsque vous utilisez SharePoint Framework v1.12.1 ou version antérieure.

Cela est dû au fait que le workbench local a été supprimé de SharePoint Framework dans la version 1.13.

Vous pouvez utiliser la même méthode pour créer une source de données fictive si vous avez implémenté des tests automatisés dans votre projet à l’aide de l’option d’énumération EnvironmentType.Test.

Récupération des données de liste

  1. Accédez à la méthode render() et remplacez le code à l’intérieur de la méthode par le suivant :

    this.domElement.innerHTML = `
      <div class="${ styles.helloWorld }">
        <div class="${ styles.container }">
          <div class="${ styles.row }">
            <div class="${ styles.column }">
              <span class="${ styles.title }">Welcome to SharePoint!</span>
              <p class="${ styles.subTitle }">Customize SharePoint experiences using web parts.</p>
              <p class="${ styles.description }">${escape(this.properties.description)}</p>
              <p class="${ styles.description }">${escape(this.properties.test)}</p>
              <p class="${ styles.description }">Loading from ${escape(this.context.pageContext.web.title)}</p>
              <a href="https://aka.ms/spfx" class="${ styles.button }">
                <span class="${ styles.label }">Learn more</span>
              </a>
            </div>
          </div>
          <div id="spListContainer" />
        </div>
      </div>`;
    
    this._renderListAsync();
    
  2. Enregistrez le fichier.

    Notez que dans la fenêtre console gulp serve, il reconstruit le code. Veillez à ne pas voir d’erreurs.

  3. Si vous utilisez SharePoint Framework v1.12.1 ou version antérieure, par exemple si vous êtes sur SharePoint Server en local, basculez vers votre workbench local et ajoutez le composant WebPart HelloWorld.

    Vous devriez normalement voir les données fictives renvoyées.

    Affichage des données de listes à partir de l’hôte local

  4. Passez sur l’instance Workbench hébergée dans SharePoint. Actualisez la page et ajoutez le composant WebPart HelloWorld.

    Vous devriez voir les listes renvoyées par le site actuel.

    Affichage des données de listes à partir de SharePoint

  5. Vous pouvez maintenant arrêter l’exécution du serveur. Passez sur la console et arrêtez gulp serve. Sélectionnez CTRL+C pour arrêter la tâche gulp.

Étapes suivantes

Félicitations, vous avez connecté votre composant WebPart aux données des listes SharePoint.

Vous pouvez continuer à développer votre composant WebPart HelloWorld dans la rubrique suivante, Déployer votre composant WebPart sur une page SharePoint. Vous allez découvrir comment déployer le composant WebPart HelloWorld et en afficher un aperçu dans une page SharePoint.