Desambiguação de componente do Microsoft Graph Toolkit

O Microsoft Graph Toolkit é criado usando componentes da Web. Os componentes da Web usam seu nome de marca como uma chave exclusiva ao se registrarem em um navegador. Qualquer tentativa de registrar um componente usando um nome de marca registrado anteriormente resulta em um erro ao chamar CustomElementRegistry.define(). Em cenários em que vários aplicativos personalizados podem ser carregados em uma única página, isso cria problemas para o Microsoft Graph Toolkit, principalmente ao desenvolver soluções usando a Estrutura do SharePoint.

O mgt-spfx pacote ajuda a atenuar esse desafio. Usando mgt-spfxo , você pode centralizar o registro dos componentes da Web do Microsoft Graph Toolkit em todas as soluções SPFx implantadas no locatário. Ao reutilizar os componentes do kit de ferramentas de um local central, as Web Parts de diferentes soluções podem ser carregadas em uma única página sem gerar erros. Quando você usa mgt-spfx, todas as Web Parts baseadas no Microsoft Graph Toolkit em um locatário do SharePoint usam a mesma versão do kit de ferramentas.

O recurso de desambiguação permite criar web parts usando a versão mais recente do Microsoft Graph Toolkit e carregá-las em páginas junto com web parts que usam v2.x. Usando esse recurso, é possível especificar uma cadeia de caracteres exclusiva a ser adicionada ao nome da marca de todos os componentes da Web do kit de ferramentas em seu aplicativo. Ao usar a desambiguação, o valor fornecido é inserido como o segundo segmento do nome da tag, portanto, ao usar customElementHelper.withDisambiguation('foo') a tag, é referenciado <mgt-login> usando <mgt-foo-login>.

Quando você registra elementos personalizados chamando CustomElementRegistry.define(), o nome inserido deve ser um nome de elemento personalizado válido. Para uma melhor experiência do desenvolvedor, o método converte withDisambiguation automaticamente o valor fornecido em letras minúsculas e emite um aviso no console do desenvolvedor se o valor fornecido contiver caracteres não minúsculos. Esse método auxiliar não limpa completamente a entrada, e a chamada do método subjacente define ainda pode falhar com um erro como DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mgt-MyName-flyout" is not a valid custom element name.

Uso em Web Parts da Estrutura do SharePoint com o React

Ao criar Web Parts da Estrutura do SharePoint usando o @microsoft/mgt-react React, qualquer componente importado da biblioteca deve ser carregado de forma assíncrona após a configuração de desambiguação. A lazyLoadComponent função auxiliar existe para facilitar o uso React.lazy e React.Suspense o carregamento lento desses componentes da Web Part de nível superior. A lazyLoadComponent função é fornecida no @microsft/mgt-spfx-utils pacote. Como o valor de desambiguação é usado apenas ao renderizar o componente da web, não há alteração na forma como um determinado componente é referenciado no código React.

O exemplo a seguir mostra uma Web Part mínima que mostra como usar o Microsoft Graph Toolkit com desambiguação em Web Parts da Estrutura do SharePoint baseada em React. Para obter exemplos mais completos, consulte o Exemplo de Web Part do SharePoint do React.

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

Observação: Se a Web Part de nível superior importar qualquer código de ou @microsoft/mgt-react@microsoft/mgt-components, a desambiguação não terá efeito.

Os componentes subjacentes podem usar componentes @microsoft/mgt-react do kit de ferramentas do pacote como de costume. Devido às etapas de configuração anteriores, os componentes do React do kit de ferramentas renderizarão HTML usando os nomes de tag desambiguados:

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

Para fazer uso da desambiguação em um aplicativo React, chame customElementHelper.withDisambiguation() antes de carregar e renderizar seu componente raiz. Para ajudar no carregamento lento nesse cenário, o React fornece a função e Suspense o lazy componente no React versão 16.6 e superior.

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 em HTML e JavaScript padrão

Para usar o recurso de desambiguação ao usar HTML e JavaScript padrão, chame customElementHelper.withDisambiguation() antes de importar o @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>

Importações dinâmicas (carregamento lento)

Usando importações dinâmicas, você pode carregar dependências de forma assíncrona. Esse padrão permite que você carregue dependências somente quando necessário. Por exemplo, talvez você queira carregar um componente somente quando um usuário clicar em um botão. Essa é uma ótima maneira de reduzir o tempo de carregamento inicial do seu aplicativo. No contexto da desambiguação, você precisa usar essa técnica porque os componentes se registram no navegador quando são importados.

Importante: Se você importar os componentes antes de aplicar a desambiguação, a desambiguação não será aplicada e o uso do nome da tag desambiguada não funcionará.

Ao usar uma import instrução, a instrução de importação é içada e executada antes de qualquer outro código no bloco de código. Para usar importações dinâmicas, você deve usar a import() função. A import() função retorna uma promessa que é resolvida para o módulo. Você também pode usar o método para executar o then código depois que o módulo é carregado e o método para lidar com quaisquer erros, catch se necessário.

Exemplo usando importações 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
});

Exemplo usando importações 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>';

Observação: Você não pode usar a desambiguação com importações estáticas.