Desambiguação de componentes do Microsoft Graph Toolkit

O Microsoft Graph Toolkit é criado com componentes Web. Os componentes Web utilizam o nome da etiqueta como uma chave exclusiva ao registarem-se num browser. Qualquer tentativa de registar um componente com um nome de etiqueta registado anteriormente resulta num erro ao chamar CustomElementRegistry.define(). Em cenários em que várias aplicações personalizadas podem ser carregadas para uma única página, isto cria problemas para o Microsoft Graph Toolkit, nomeadamente ao desenvolver soluções com Estrutura do SharePoint.

O mgt-spfx pacote ajuda a mitigar este desafio. Ao utilizar mgt-spfxo , pode centralizar o registo de componentes Web do Microsoft Graph Toolkit em todas as soluções SPFx implementadas no inquilino. Ao reutilizar componentes do toolkit a partir de uma localização central, as peças Web de diferentes soluções podem ser carregadas para uma única página sem gerar erros. Quando utiliza mgt-spfxo , todas as peças Web baseadas no Microsoft Graph Toolkit num inquilino do SharePoint utilizam a mesma versão do toolkit.

A funcionalidade de desambiguação permite-lhe criar peças Web com a versão mais recente do Microsoft Graph Toolkit e carregá-las em páginas juntamente com peças Web que utilizam v2.x. Ao utilizar esta funcionalidade, pode especificar uma cadeia exclusiva para adicionar ao nome da etiqueta de todos os componentes Web do toolkit na respetiva aplicação. Ao utilizar a desambiguação, o valor fornecido é inserido como o segundo segmento do nome da etiqueta, pelo que ao utilizar customElementHelper.withDisambiguation('foo') a <mgt-login> etiqueta é referenciado com <mgt-foo-login>.

Quando regista elementos personalizados a chamar CustomElementRegistry.define(), o nome introduzido tem de ser um nome de elemento personalizado válido. Para uma melhor experiência de programador, o withDisambiguation método converte automaticamente o valor fornecido em minúsculas e emite um aviso na consola do programador se o valor fornecido contiver carateres não minúsculos. Este 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.

Utilização em peças Web Estrutura do SharePoint com React

Ao criar Estrutura do SharePoint peças Web com React, qualquer componente que importe da @microsoft/mgt-react biblioteca tem de ser carregado de forma assíncrona depois de configurar a definição de desambiguação. A lazyLoadComponent função auxiliar existe para facilitar a utilização React.lazy e React.Suspense para carregar lentamente estes componentes a partir da peça Web de nível superior. A lazyLoadComponent função é fornecida no @microsft/mgt-spfx-utils pacote. Uma vez que o valor de desambiguação só é utilizado ao compor o componente Web, não existe nenhuma alteração na forma como um determinado componente é referenciado no código React.

O exemplo seguinte mostra uma peça Web mínima que mostra como utilizar o Microsoft Graph Toolkit com desambiguação em peças Web Estrutura do SharePoint baseadas em React. Para obter exemplos mais completos, veja o Exemplo de Peças Web 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
}

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

Os componentes subjacentes podem, em seguida, utilizar componentes do toolkit do @microsoft/mgt-react pacote como habitualmente. Devido aos passos de configuração anteriores, o toolkit React componentes irão compor HTML com os nomes de etiquetas 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>
    );
  }
}

Utilização no React

Para utilizar a desambiguação numa aplicação React, chame customElementHelper.withDisambiguation() antes de carregar e compor o componente raiz. Para ajudar com o carregamento em diferido neste cenário, React fornece a função e Suspense o lazy componente na React versão 16.6 ou 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'));

Utilização em HTML padrão e JavaScript

Para utilizar a funcionalidade de desambiguação ao utilizar 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 em diferido)

Ao utilizar importações dinâmicas, pode carregar dependências de forma assíncrona. Este padrão permite-lhe carregar dependências apenas quando necessário. Por exemplo, poderá querer carregar um componente apenas quando um utilizador clica num botão. Esta é uma excelente forma de reduzir o tempo de carregamento inicial da sua aplicação. No contexto da desambiguação, tem de utilizar esta técnica porque os componentes registam-se no browser quando são importados.

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

Ao utilizar uma instrução import , a instrução de importação é içada e executada antes de qualquer outro código no bloco de código. Para utilizar importações dinâmicas, tem de utilizar a import() função . A import() função devolve uma promessa que é resolvida para o módulo. Também pode utilizar o método para executar o then código após o carregamento do módulo e o catch método para processar quaisquer erros, se necessário.

Exemplo com 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 com 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>';

Nota: Não pode utilizar a desambiguação com importações estáticas.