Mehrdeutigkeit der Komponenten des Microsoft Graph-Toolkits

Das Microsoft Graph-Toolkit wird mithilfe von Webkomponenten erstellt. Webkomponenten verwenden ihren Tagnamen bei der Registrierung in einem Browser als eindeutigen Schlüssel. Jeder Versuch, eine Komponente mit einem zuvor registrierten Tagnamen zu registrieren, führt beim Aufrufen CustomElementRegistry.define()von zu einem Fehler. In Szenarien, in denen mehrere benutzerdefinierte Anwendungen auf eine einzelne Seite geladen werden können, führt dies zu Problemen mit dem Microsoft Graph-Toolkit, insbesondere bei der Entwicklung von Lösungen mit SharePoint-Framework.

Das mgt-spfx Paket trägt dazu bei, diese Herausforderung zu entschärfen. Mithilfe von mgt-spfxkönnen Sie die Registrierung von Microsoft Graph Toolkit-Webkomponenten für alle SPFx-Lösungen zentralisieren, die auf dem Mandanten bereitgestellt werden. Durch die Wiederverwendung von Toolkitkomponenten von einem zentralen Ort aus können Webparts aus verschiedenen Lösungen auf eine einzelne Seite geladen werden, ohne Fehler zu verursachen. Wenn Sie verwenden mgt-spfx, verwenden alle Auf dem Microsoft Graph-Toolkit basierenden Webparts in einem SharePoint-Mandanten dieselbe Version des Toolkits.

Mit dem Mehrdeutigkeitsfeature können Sie Webparts mit der neuesten Version des Microsoft Graph-Toolkits erstellen und auf Seiten zusammen mit Webparts laden, die v2.x verwenden. Mithilfe dieses Features können Sie eine eindeutige Zeichenfolge angeben, die dem Tagnamen aller Toolkit-Webkomponenten in ihrer Anwendung hinzugefügt werden soll. Bei Verwendung von Mehrdeutigkeit wird der angegebene Wert als zweites Segment des Tagnamens eingefügt, sodass bei Verwendung customElementHelper.withDisambiguation('foo') des <mgt-login> Tags mithilfe von <mgt-foo-login>verwiesen wird.

Wenn Sie benutzerdefinierte Elemente registrieren, die aufrufen CustomElementRegistry.define(), muss der eingegebene Name ein gültiger benutzerdefinierter Elementname sein. Für eine bessere Entwicklererfahrung konvertiert die withDisambiguation -Methode den angegebenen Wert automatisch in Kleinbuchstaben und gibt eine Warnung in der Entwicklerkonsole aus, wenn der angegebene Wert Keine Kleinbuchstaben enthält. Diese Hilfsmethode behebt die Eingabe nicht vollständig, und der zugrunde liegende define Methodenaufruf schlägt möglicherweise trotzdem mit einem Fehler wie DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mgt-MyName-flyout" is not a valid custom element namefehl.

Verwendung in SharePoint-Framework Webparts mit React

Beim Erstellen SharePoint-Framework Webparts mit React muss jede Komponente, die aus der @microsoft/mgt-react Bibliothek importiert wird, nach dem Konfigurieren der Mehrdeutigkeitseinstellung asynchron geladen werden. Die lazyLoadComponent Hilfsfunktion ist vorhanden, um die Verwendung React.lazy und React.Suspense das verzögerte Laden dieser Komponenten aus dem Webpart der obersten Ebene zu erleichtern. Die lazyLoadComponent Funktion wird im @microsft/mgt-spfx-utils Paket bereitgestellt. Da der Mehrdeutigkeitswert nur beim Rendern der Webkomponente verwendet wird, gibt es keine Änderung an der Art und Weise, wie in React Code auf eine bestimmte Komponente verwiesen wird.

Das folgende Beispiel zeigt ein minimales Webpart, das zeigt, wie Das Microsoft Graph-Toolkit mit Mehrdeutigkeit in React-basierten SharePoint-Framework-Webparts verwendet wird. Ausführlichere Beispiele finden Sie im React SharePoint-Webpartbeispiel.

// [...] 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
}

Hinweis: Wenn das Webpart der obersten Ebene Code aus @microsoft/mgt-react oder @microsoft/mgt-componentsimportiert, hat die Mehrdeutigkeit keine Auswirkungen.

Die zugrunde liegenden Komponenten können dann wie gewohnt Toolkitkomponenten aus dem @microsoft/mgt-react Paket verwenden. Aufgrund der früheren Setupschritte rendert das Toolkit React Komponenten HTML mit den eindeutigen Tagnamen:

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>
    );
  }
}

Verwendung in React

Um die Mehrdeutigkeit in einer React Anwendung zu nutzen, rufen Sie customElementHelper.withDisambiguation() auf, bevor Sie Ihre Stammkomponente laden und rendern. Um das verzögerte Laden in diesem Szenario zu unterstützen, stellt React die lazy Funktion und Suspense Komponente in React Version 16.6 und höher bereit.

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'));

Verwendung in Standard-HTML und JavaScript

Um das Mehrdeutigkeitsfeature bei Verwendung von Standard-HTML und JavaScript zu verwenden, rufen Sie customElementHelper.withDisambiguation() vor dem Importieren des Moduls @microsoft/mgt-components auf.

<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>

Wichtig

Der import von mgt-components muss einen dynamischen Import verwenden, um sicherzustellen, dass die Mehrdeutigkeit vor dem Importieren der Komponenten angewendet wird. Wenn ein statischer Import verwendet wird, wird er angehoben , und der Import erfolgt, bevor die Mehrdeutigkeit angewendet werden kann.

Dynamische Importe (verzögertes Laden)

Mithilfe dynamischer Importe können Sie Abhängigkeiten asynchron laden. Mit diesem Muster können Sie Abhängigkeiten nur bei Bedarf laden. Beispielsweise können Sie eine Komponente nur laden, wenn ein Benutzer auf eine Schaltfläche klickt. Dies ist eine hervorragende Möglichkeit, die anfängliche Ladezeit Ihrer Anwendung zu reduzieren. Im Kontext der Mehrdeutigkeit müssen Sie diese Technik verwenden, da Komponenten sich beim Importieren im Browser registrieren.

Wichtig: Wenn Sie die Komponenten importieren, bevor Sie die Mehrdeutigkeit angewendet haben, wird die Mehrdeutigkeit nicht angewendet, und die Verwendung des eindeutigen Tagnamens funktioniert nicht.

Bei Verwendung einer import -Anweisung wird die import-Anweisung angehoben und vor jedem anderen Code im Codeblock ausgeführt. Um dynamische Importe zu verwenden, müssen Sie die import() -Funktion verwenden. Die import() Funktion gibt eine Zusage zurück, die in das Modul aufgelöst wird. Sie können auch die then -Methode verwenden, um Code auszuführen, nachdem das Modul geladen wurde, und die catch -Methode, um ggf. Fehler zu behandeln.

Beispiel für dynamische Importe

// 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
});

Beispiel für statische Importe

// 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>';

Hinweis: Sie können keine Mehrdeutigkeit bei statischen Importen verwenden.