Desambiguación de componentes del kit de herramientas de Microsoft Graph

Microsoft Graph Toolkit se compila mediante componentes web. Los componentes web usan su nombre de etiqueta como clave única al registrarse en un explorador. Cualquier intento de registrar un componente con un nombre de etiqueta registrado anteriormente produce un error al llamar a CustomElementRegistry.define(). En escenarios en los que se pueden cargar varias aplicaciones personalizadas en una sola página, esto crea problemas para Microsoft Graph Toolkit, especialmente al desarrollar soluciones mediante SharePoint Framework.

El mgt-spfx paquete ayuda a mitigar este desafío. mgt-spfxMediante , puede centralizar el registro de componentes web de Microsoft Graph Toolkit en todas las soluciones SPFx implementadas en el inquilino. Al reutilizar los componentes del kit de herramientas desde una ubicación central, los elementos web de diferentes soluciones se pueden cargar en una sola página sin producir errores. Al usar mgt-spfx, todos los elementos web basados en Microsoft Graph Toolkit en un inquilino de SharePoint usan la misma versión del kit de herramientas.

La característica de desambiguación le permite crear elementos web con la versión más reciente de Microsoft Graph Toolkit y cargarlos en páginas junto con elementos web que usan v2.x. Con esta característica, puede especificar una cadena única para agregar al nombre de etiqueta de todos los componentes web del kit de herramientas de su aplicación. Cuando se usa la desambiguación, el valor proporcionado se inserta como el segundo segmento del nombre de la etiqueta, por lo que cuando se usa customElementHelper.withDisambiguation('foo') la <mgt-login> etiqueta se hace referencia mediante <mgt-foo-login>.

Al registrar elementos personalizados que llaman a CustomElementRegistry.define(), el nombre especificado debe ser un nombre de elemento personalizado válido. Para mejorar la experiencia del desarrollador, el withDisambiguation método convierte automáticamente el valor proporcionado en minúsculas y emite una advertencia en la consola del desarrollador si el valor proporcionado contiene caracteres que no son minúsculas. Este método auxiliar no sane completamente la entrada y la llamada al método subyacente define puede seguir generando un error como DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mgt-MyName-flyout" is not a valid custom element name.

Uso en SharePoint Framework elementos web con React

Al compilar SharePoint Framework elementos web mediante React, cualquier componente que importe desde la @microsoft/mgt-react biblioteca debe cargarse de forma asincrónica después de configurar la configuración de desambiguación. La lazyLoadComponent función auxiliar existe para facilitar el uso React.lazy y React.Suspense la carga diferida de estos componentes desde el elemento web de nivel superior. La lazyLoadComponent función se proporciona en el @microsft/mgt-spfx-utils paquete. Dado que el valor de desambiguación solo se usa al representar el componente web, no hay ningún cambio en la forma en que se hace referencia a un componente determinado en React código.

En el ejemplo siguiente se muestra un elemento web mínimo que muestra cómo usar Microsoft Graph Toolkit con desambiguación en elementos web SharePoint Framework basados en React. Para obtener ejemplos más completos, vea el React ejemplo de elemento web de 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
}

Nota: Si el elemento web de nivel superior importa cualquier código de o @microsoft/mgt-react@microsoft/mgt-components, la desambiguación no tendrá ningún efecto.

Los componentes subyacentes pueden usar los componentes del kit de herramientas del @microsoft/mgt-react paquete como de costumbre. Debido a los pasos de configuración anteriores, el kit de herramientas React componentes representará HTML mediante los nombres de etiquetas no ambigüadas:

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

Uso en React

Para usar la desambiguación en una aplicación React, llame a customElementHelper.withDisambiguation() antes de cargar y representar el componente raíz. Para ayudar con la carga diferida en este escenario, React proporciona la función y Suspense el lazy componente en React versión 16.6 y versiones anteriores.

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

Uso en HTML estándar y JavaScript

Para usar la característica de desambiguación al usar HTML y JavaScript estándar, llame customElementHelper.withDisambiguation() a antes de importar el @microsoft/mgt-components módulo.

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

Importante

El import de mgt-components debe usar una importación dinámica para asegurarse de que se aplica la desambiguación antes de importar los componentes. Si se usa una importación estática, se eleva y la importación se producirá antes de que se pueda aplicar la desambiguación.

Importaciones dinámicas (carga diferida)

Con las importaciones dinámicas, puede cargar las dependencias de forma asincrónica. Este patrón le permite cargar las dependencias solo cuando sea necesario. Por ejemplo, es posible que quiera cargar un componente solo cuando un usuario hace clic en un botón. Esta es una excelente manera de reducir el tiempo de carga inicial de la aplicación. En el contexto de la desambiguación, debe usar esta técnica porque los componentes se registran a sí mismos en el explorador cuando se importan.

Importante: Si importa los componentes antes de aplicar la desambiguación, no se aplicará la desambiguación y el uso del nombre de etiqueta desambiguado no funcionará.

Cuando se usa una import instrucción , la instrucción import se eleva y se ejecuta antes que cualquier otro código del bloque de código. Para usar importaciones dinámicas, debe usar la import() función . La import() función devuelve una promesa que se resuelve en el módulo. También puede usar el then método para ejecutar código después de cargar el módulo y el catch método para controlar los errores si es necesario.

Ejemplo de uso de importaciones dinámicas

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

Ejemplo de uso de importaciones estáticas

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

Nota: No se puede usar la desambiguación con importaciones estáticas.