Levée de l’ambiguïté des composants du Kit de ressources Microsoft Graph

Le Kit de ressources Microsoft Graph est créé à l’aide de composants web. Les composants web utilisent leur nom de balise comme clé unique lors de l’inscription dans un navigateur. Toute tentative d’inscription d’un composant à l’aide d’un nom de balise précédemment inscrit génère une erreur lors de l’appel CustomElementRegistry.define()de . Dans les scénarios où plusieurs applications personnalisées peuvent être chargées dans une seule page, cela crée des problèmes pour microsoft Graph Toolkit, notamment lors du développement de solutions à l’aide de SharePoint Framework.

Le mgt-spfx package permet d’atténuer ce problème. À l’aide de mgt-spfx, vous pouvez centraliser l’inscription des composants web du Kit de ressources Microsoft Graph sur toutes les solutions SPFx déployées sur le locataire. En réutilisant les composants du kit de ressources à partir d’un emplacement central, les composants WebPart de différentes solutions peuvent être chargés dans une seule page sans générer d’erreurs. Lorsque vous utilisez mgt-spfx, tous les composants WebPart basés sur le Kit de ressources Microsoft Graph dans un locataire SharePoint utilisent la même version du kit de ressources.

La fonctionnalité de levée d’ambiguïté vous permet de créer des composants WebPart à l’aide de la dernière version du Kit de ressources Microsoft Graph et de les charger sur des pages avec des composants WebPart qui utilisent v2.x. À l’aide de cette fonctionnalité, vous pouvez spécifier une chaîne unique à ajouter au nom de la balise de tous les composants web du kit de ressources dans leur application. Lors de l’utilisation de la levée d’ambiguïté, la valeur fournie est insérée en tant que deuxième segment du nom de la balise, de sorte que lors de l’utilisation customElementHelper.withDisambiguation('foo') de la <mgt-login> balise est référencée à l’aide <mgt-foo-login>de .

Lorsque vous inscrivez des éléments personnalisés appelant CustomElementRegistry.define(), le nom entré doit être un nom d’élément personnalisé valide. Pour une meilleure expérience de développement, la withDisambiguation méthode convertit automatiquement la valeur fournie en minuscules et émet un avertissement dans la console du développeur si la valeur fournie contient des caractères non minuscules. Cette méthode d’assistance n’assainit pas complètement l’entrée, et l’appel de méthode sous-jacent define peut toujours échouer avec une erreur comme DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mgt-MyName-flyout" is not a valid custom element name.

Utilisation dans SharePoint Framework composants WebPart avec React

Lors de la génération de SharePoint Framework composants WebPart à l’aide de React, tout composant importé à partir de la @microsoft/mgt-react bibliothèque doit être chargé de manière asynchrone après avoir configuré le paramètre de levée d’ambiguïté. La lazyLoadComponent fonction d’assistance existe pour faciliter l’utilisation React.lazy et React.Suspense le chargement différé de ces composants à partir du composant WebPart de niveau supérieur. La lazyLoadComponent fonction est fournie dans le @microsft/mgt-spfx-utils package. Étant donné que la valeur de levée d’ambiguïté est utilisée uniquement lors du rendu du composant web, aucune modification n’est apportée à la façon dont un composant donné est référencé dans React code.

L’exemple suivant montre un composant WebPart minimal qui montre comment utiliser le Kit de ressources Microsoft Graph avec la levée d’ambiguïté dans les composants WebPart SharePoint Framework basés sur React. Pour obtenir des exemples plus complets, consultez l’exemple de composant WebPart React SharePoint.

// [...] trimmed for brevity
import { Providers } from '@microsoft/mgt-element/dist/es6/providers/Providers';
import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider/dist/es6/SharePointProvider';
import { lazyLoadComponent } from '@microsoft/mgt-spfx-utils';

// Async import of component that imports the React Components
const MgtDemo = React.lazy(() => import('./components/MgtDemo'));

export interface IMgtDemoWebPartProps {
  description: string;
}
// set the disambiguation before initializing any webpart
// Use the solution name to ensure unique tag names
customElementHelper.withDisambiguation('spfx-solution-name');

export default class MgtDemoWebPart extends BaseClientSideWebPart<IMgtDemoWebPartProps> {
  // set the global provider
  protected async onInit() {
    if (!Providers.globalProvider) {
      Providers.globalProvider = new SharePointProvider(this.context);
    }
  }

  public render(): void {
    const element = lazyLoadComponent(MgtDemo, { description: this.properties.description });

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

  // [...] trimmed for brevity
}

Note: Si le composant WebPart de niveau supérieur importe du code à partir de @microsoft/mgt-react ou @microsoft/mgt-components, la levée d’ambiguïté n’aura aucun effet.

Les composants sous-jacents peuvent ensuite utiliser les composants du kit de ressources du @microsoft/mgt-react package comme d’habitude. En raison des étapes d’installation antérieures, le kit de ressources React composants affiche le code HTML à l’aide des noms de balises ambiguïtés :

import { Person } from '@microsoft/mgt-react';

// [...] trimmed for brevity

export default class MgtReact extends React.Component<IMgtReactProps, {}> {
  public render(): React.ReactElement<IMgtReactProps> {
    return (
      <div className={ styles.mgtReact }>
        <Person personQuery="me" />
      </div>
    );
  }
}

Utilisation dans React

Pour utiliser la levée d’ambiguïté dans une application React, appelez customElementHelper.withDisambiguation() avant de charger et de restituer votre composant racine. Pour faciliter le chargement différé dans ce scénario, React fournit la fonction et Suspense le lazy composant dans React version 16.6 et ultérieure.

import React, { lazy, Suspense } from 'react';
import ReactDOM from 'react-dom';
import { customElementHelper, Providers } from '@microsoft/mgt-element';
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

customElementHelper.withDisambiguation('contoso');

Providers.globalProvider = new Msal2Provider({ clientId: 'clientId' });

const App = lazy(() => import('./App'));
ReactDOM.render(<Suspense fallback='...'><App /></Suspense>, document.getElementById('root'));

Utilisation dans html standard et JavaScript

Pour utiliser la fonctionnalité de levée d’ambiguïté lors de l’utilisation du code HTML et javaScript standard, appelez customElementHelper.withDisambiguation() avant d’importer le @microsoft/mgt-components module.

<script type="module">
  import { Providers, customElementHelper } from '@microsoft/mgt-element';
  import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
  // configure disambiguation
  customElementHelper.withDisambiguation('contoso');

  // initialize the auth provider globally
  Providers.globalProvider = new Msal2Provider({clientId: 'clientId'});

  // import the components using dynamic import to avoid hoisting
  import('@microsoft/mgt-components');
</script>

<mgt-contoso-login></mgt-contoso-login>
<mgt-contoso-person person-query="Bill Gates" person-card="hover"></mgt-contoso-person>
<mgt-contoso-agenda group-by-day></mgt-contoso-agenda>

Importations dynamiques (chargement différé)

À l’aide des importations dynamiques, vous pouvez charger des dépendances de manière asynchrone. Ce modèle vous permet de charger des dépendances uniquement si nécessaire. Par exemple, vous pouvez charger un composant uniquement lorsqu’un utilisateur clique sur un bouton. Il s’agit d’un excellent moyen de réduire le temps de chargement initial de votre application. Dans le contexte de la levée d’ambiguïté, vous devez utiliser cette technique, car les composants s’inscrivent eux-mêmes dans le navigateur lorsqu’ils sont importés.

Important: Si vous importez les composants avant d’avoir appliqué l’ambiguïté, la levée d’ambiguïté ne sera pas appliquée et l’utilisation du nom de balise désambiguée ne fonctionnera pas.

Lors de l’utilisation d’une import instruction, l’instruction import est hissée et s’exécute avant tout autre code dans le bloc de code. Pour utiliser des importations dynamiques, vous devez utiliser la import() fonction . La import() fonction retourne une promesse qui se résout en module. Vous pouvez également utiliser la méthode pour exécuter du then code après le chargement du module et la catch méthode pour gérer les erreurs si nécessaire.

Exemple utilisant des importations dynamiques

// static import via a statement
import { Providers, customElementHelper } from '@microsoft/mgt-element';
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

customElementHelper.withDisambiguation('contoso');
Providers.globalProvider = new Msal2Provider({clientId: 'clientId'});

// dynamic import via a function
import('@microsoft/mgt-components').then(() => {
  // code to execute after the module is loaded
  document.body.innerHTML = '<mgt-contoso-login></mgt-contoso-login>';
}).catch((e) => {
  // handle any errors
});

Exemple utilisant des importations statiques

// static import via a statement
import { Providers } from '@microsoft/mgt-element';
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
import '@microsoft/mgt-components';

Providers.globalProvider = new Msal2Provider({clientId: 'clientId'});

document.body.innerHTML = '<mgt-login></mgt-login>';

Note: Vous ne pouvez pas utiliser la levée d’ambiguïté avec les importations statiques.