Créer un composant WebPart SharePoint avec la Boîte à outils Microsoft Graph

  • Article

Cet article explique comment utiliser les composants du Kit de ressources Microsoft Graph dans un composant WebPart côté client SharePoint. La prise en main comporte les étapes suivantes :

  1. Configurez votre environnement de développement.
  2. Créez votre projet de composant WebPart.
  3. Ajoutez les packages du Kit de ressources Microsoft Graph.
  4. Ajoutez le fournisseur SharePoint.
  5. Ajoutez des composants.
  6. Configurez les autorisations.
  7. Configurer webpack
  8. Créez et déployez votre composant WebPart.
  9. Testez votre le composant WebPart.

Configuration de votre environnement de développement SharePoint Framework et création d’un composant WebPart

Suivez les étapes pour Configurer votre environnement de développement SharePoint Framework.

Créer votre projet de composant WebPart

Suivez les instructions pour créer un composant WebPart. Lorsque vous êtes invité à choisir le modèle que vous souhaitez utiliser, choisissez React.

Importante

Vous devez choisir React lors de la sélection de votre infrastructure lorsque vous utilisez yo @microsoft/sharepoint.

Ajouter les packages du Kit de ressources Microsoft Graph

Le Kit de ressources Microsoft Graph publie plusieurs packages nécessaires à la création d’un composant WebPart SharePoint Framework. L’installation des @microsoft/mgt-elementpackages , @microsoft/mgt-react, @microsoft/mgt-sharepoint-provideret @microsoft/mgt-spfx-utils installe les dépendances nécessaires.

npm install @microsoft/mgt-element @microsoft/mgt-react @microsoft/mgt-sharepoint-provider @microsoft/mgt-spfx-utils

Ajouter le fournisseur SharePoint

Les fournisseurs de la Boîte à outils Microsoft Graph activent l’authentification et l’accès à Microsoft Graph pour les composants. Pour en savoir plus, consultez Utilisation des fournisseurs. Les composants WebPart SharePoint existent toujours dans un contexte authentifié, car l’utilisateur est authentifié pour accéder à la page qui héberge votre composant WebPart. Utilisez ce contexte pour initialiser le fournisseur SharePoint.

Premièrement, ajoutez le fournisseur à votre composant WebPart. Localisez le fichier src\webparts\<your-project>\<your-web-part>.ts dans le dossier de votre projet, puis ajoutez la ligne suivante dans la partie supérieure de votre fichier, juste en-dessous des instructions import existantes :

import { Providers } from '@microsoft/mgt-element';
import { SharePointProvider } from "@microsoft/mgt-sharepoint-provider";

Ensuite, initialisez le fournisseur avec le contexte authentifié à l’intérieur de la onInit() méthode de votre composant WebPart. Dans le même fichier, ajoutez le code suivant juste avant la ligne public render(): void { :

protected async onInit() {
  if (!Providers.globalProvider) {
    Providers.globalProvider = new SharePointProvider(this.context);
  }
}

Configurer la levée d’ambiguïté

Pour vous assurer que votre composant WebPart fonctionne s’il existe plusieurs solutions de composants WebPart utilisant le Kit de ressources Microsoft Graph dans une seule page, vous devez utiliser la levée d’ambiguïté. Pour plus d’informations, consultez l’ambiguïté.

Tout d’abord, mettez à jour vos importations à partir de @microsoft/mgt-element et ajoutez-en une pour l’assistance lazyLoadComponent .

import { Providers, customElementHelper } from "@microsoft/mgt-element";
import { lazyLoadComponent } from "@microsoft/mgt-spfx-utils";

Ensuite, mettez à jour la onInit() méthode du composant WebPart racine pour configurer la levée d’ambiguïté. La chaîne utilisée pour lever l’ambiguïté doit être propre à votre solution SharePoint Framework :

protected async onInit(): Promise<void> {
  if (!Providers.globalProvider) {
    Providers.globalProvider = new SharePointProvider(this.context);
  }
  customElementHelper.withDisambiguation('contoso-hr-solution');
  return super.onInit();
}

Mettre à jour l’importation et le rendu du composant React

Tout d’abord, convertissez l’importation du composant pour utiliser React.lazy. Recherchez l’instruction import <WebPartName> from './components/<WebPartName>; et mettez-la à jour avec les éléments suivants :

const MgtComponent = React.lazy(
  () =>
    import(/* webpackChunkName: 'mgt-react-component' */ "./components/<WebPartName>")
);

Ensuite, modifiez la méthode render pour utiliser l’assistance lazyLoadComponent :

  public render(): void {
    const element = lazyLoadComponent<IHelloWorldProps>(MgtComponent, {
      description: this.properties.description,
      isDarkTheme: this._isDarkTheme,
      environmentMessage: this._environmentMessage,
      hasTeamsContext: !!this.context.sdks.microsoftTeams,
      userDisplayName: this.context.pageContext.user.displayName
    });

    ReactDom.render(element, this.domElement);
  }

Votre composant WebPart doit maintenant ressembler à ceci :

import * as React from "react";
import * as ReactDom from "react-dom";
import { Version } from "@microsoft/sp-core-library";
import {
  type IPropertyPaneConfiguration,
  PropertyPaneTextField,
} from "@microsoft/sp-property-pane";
import { BaseClientSideWebPart } from "@microsoft/sp-webpart-base";
import { IReadonlyTheme } from "@microsoft/sp-component-base";
import { Providers, customElementHelper } from "@microsoft/mgt-element";
import { lazyLoadComponent } from "@microsoft/mgt-spfx-utils";
import { SharePointProvider } from "@microsoft/mgt-sharepoint-provider";

import * as strings from "HelloWorldWebPartStrings";
const HelloWorld = React.lazy(
  () =>
    import(
      /* webpackChunkName: 'mgt-react-component' */ "./components/HelloWorld"
    )
);
import { IHelloWorldProps } from "./components/IHelloWorldProps";

export interface IHelloWorldWebPartProps {
  description: string;
}

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  private _isDarkTheme: boolean = false;
  private _environmentMessage: string = "";

  public render(): void {
    const element = lazyLoadComponent<IHelloWorldProps>(HelloWorld, {
      description: this.properties.description,
      isDarkTheme: this._isDarkTheme,
      environmentMessage: this._environmentMessage,
      hasTeamsContext: !!this.context.sdks.microsoftTeams,
      userDisplayName: this.context.pageContext.user.displayName,
    });

    ReactDom.render(element, this.domElement);
  }

  protected async onInit(): Promise<void> {
    if (!Providers.globalProvider) {
      Providers.globalProvider = new SharePointProvider(this.context);
    }
    customElementHelper.withDisambiguation("contoso-hr-solution");
    return super.onInit();
  }
  // [...] trimmed for brevity
}

Ajouter des composants

Ajoutez les composants au composant React. Recherchez et ouvrez le src\webparts\<your-project>\components\<your-component>.tsx fichier et ajoutez l’importation pour le composant que vous souhaitez utiliser ( dans ce cas, le Person composant ), puis mettez à jour la render() méthode pour utiliser le composant Person. Votre composant doit maintenant ressembler à ceci :

import * as React from 'react';
import type { IHelloWorldProps } from './IHelloWorldProps';
import { Person } from '@microsoft/mgt-react';

export default class HelloWorld extends React.Component<IHelloWorldProps, {}> {
  public render(): React.ReactElement<IHelloWorldProps> {
    return (<Person personQuery="me" view="twolines" />);
  }
}

Ou si vous préférez utiliser React composants fonctionnels :

import * as React from 'react';
import type { IHelloWorldProps } from './IHelloWorldProps';
import { Person, ViewType } from '@microsoft/mgt-react';

const HelloWorld = (props: IHelloWorldProps): React.ReactElement => <Person personQuery="me" view={ViewType.twolines} />;

export default HelloWorld;

Configuration des autorisations

Pour appeler Microsoft Graph à partir de votre application SharePoint Framework, vous devez demander les autorisations nécessaires dans le package de votre solution et un administrateur client Microsoft 365 doit approuver les autorisations demandées.

Pour ajouter les autorisations au package de votre solution, localisez et ouvrez le fichier config\package-solution.json, puis définissez :

"isDomainIsolated": false,

Juste en dessous de cette ligne, ajoutez la ligne suivante :

"webApiPermissionRequests":[],

Déterminez les autorisations microsoft API Graph dont vous avez besoin pour dépendre des composants que vous utilisez. La page de documentation de chaque composant fournit une liste des autorisations exigées par le composant. Vous devez ajouter chaque autorisation requise à webApiPermissionRequests. Par exemple, si vous utilisez le composant Personne et le composant Agenda, il est possible que votre webApiPermissionRequests ressemble à :

"webApiPermissionRequests": [
  {
    "resource": "Microsoft Graph",
    "scope": "User.Read"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "Calendars.Read"
  }
]

Configurer webpack

Pour générer votre composant WebPart, la configuration webpack SharePoint Framework doit être mise à jour pour gérer correctement javaScript moderne avec chaînage facultatif et fusion nullish via des transformations Babel supplémentaires.

Installer des packages Babel

Pour gérer correctement les dépendances qui émettent du code ES2021, un chargeur babel et certaines transformations doivent être ajoutés en tant que dépendances de développement au projet.

npm i --save-dev babel-loader@8.3.0 @babel/plugin-transform-optional-chaining @babel/plugin-transform-nullish-coalescing-operator @babel/plugin-transform-logical-assignment-operators

Modifier la configuration webpack

SharePoint Framework fournit un modèle d’extensibilité pour modifier la configuration webpack utilisée pour regrouper les composants WebPart. Recherchez et ouvrez gulpfile.js. Ajoutez le code suivant au-dessus de la ligne contenant build.initialize(require('gulp'));

const path = require("path");
const litFolders = [
  `node_modules${path.sep}lit${path.sep}`,
  `node_modules${path.sep}@lit${path.sep}`,
  `node_modules${path.sep}lit-html${path.sep}`
];
build.configureWebpack.mergeConfig({
  additionalConfiguration: generatedConfiguration => {
    generatedConfiguration.module.rules.push({
      test: /\.js$/,
      // only run on lit packages
      include: resourcePath => 
        litFolders.some(litFolder => resourcePath.includes(litFolder)),
      use: {
        loader: 'babel-loader',
        options: {
          plugins: [
            '@babel/plugin-transform-optional-chaining',
            '@babel/plugin-transform-nullish-coalescing-operator',
            '@babel/plugin-transform-logical-assignment-operators'
          ]
        }
      }
    });
    return generatedConfiguration;
  }
});

Cela garantit que le code de la lit bibliothèque est correctement traité par la chaîne de build SharePoint Framework.

Créer et déployer votre composant WebPart

À présent, vous allez créer votre application et la déployer sur SharePoint. Créez votre application en exécutant les commandes suivantes :

gulp build
gulp bundle
gulp package-solution

Dans le sharepoint/solution dossier, il y a un nouveau .sppkg fichier. Vous devez charger ce fichier dans votre catalogue d’applications SharePoint Online. Accédez à la Page fonctionnalités supplémentaires de votre Centre d’administrateur SharePoint. Sélectionnez Ouvrir sous Applications, puis Catalogue d’applications, puis Distribuer des applications pour SharePoint. Chargez votre .sppkg fichier, puis sélectionnez Déployer.

Vous devez ensuite approuver les autorisations en tant qu’administrateur.

Accédez à votre Centre d’administration SharePoint. Dans la navigation de gauche, sélectionnez Avancé, puis Accès d’API. Vous devez voir les demandes en attente pour chacune des autorisations que vous avez ajoutées dans votre fichier config\package-solution.json. Sélectionnez et approuvez chaque autorisation.

Tester votre composant WebPart

Vous êtes maintenant prêt à ajouter votre composant WebPart à une page SharePoint et à le tester. Vous devez utiliser le workbench hébergé pour tester les composants WebPart qui utilisent le Kit de ressources Microsoft Graph, car les composants ont besoin du contexte authentifié pour appeler Microsoft Graph. Vous trouverez votre workbench hébergé à l’adresse https://< YOUR_TENANT.sharepoint.com/_layouts/15/workbench.aspx>.

Ouvrez le config\serve.json fichier dans votre projet et remplacez la valeur de initialPage par l’URL de votre workbench hébergé :

"initialPage": "https://<YOUR_TENANT>.sharepoint.com/_layouts/15/workbench.aspx",

Enregistrez le fichier, puis exécutez la commande suivante dans la console pour générer et afficher un aperçu de votre composant WebPart :

gulp serve

Votre workbench hébergé s’ouvre automatiquement dans votre navigateur. Ajoutez votre composant WebPart à la page. Vous devez voir votre composant WebPart avec les composants de la Boîte à outils Microsoft Graph en action ! Tant que la commande gulp serve s’exécute dans votre console, vous pouvez continuer à modifier votre code, puis simplement actualiser votre navigateur pour afficher les modifications.

Étapes suivantes