Disambiguation de componente do Microsoft Graph Toolkit

Artigo
11/07/2024

O Kit de Ferramentas do Microsoft Graph é criado usando componentes da Web. Os componentes da Web usam o nome da 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 Estrutura do SharePoint.

O mgt-spfx pacote ajuda a atenuar esse desafio. mgt-spfxUsando o , você pode centralizar o registro de componentes Web do Microsoft Graph Toolkit em todas as soluções SPFx implantadas no locatário. Reutilizando componentes de kit de ferramentas de um local central, web parts de soluções diferentes podem ser carregadas em uma única página sem gerar erros. Quando você usa mgt-spfx, todas as web parts baseadas em Kit de Ferramentas do Microsoft Graph 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, juntamente com web parts que usam v2.x. Usando esse recurso, você pode especificar uma cadeia de caracteres exclusiva para adicionar ao nome da marca de todos os componentes web do kit de ferramentas em seu aplicativo. Ao usar a disambiguation, o valor fornecido é inserido como o segundo segmento do nome da marca, portanto, ao usar customElementHelper.withDisambiguation('foo') a <mgt-login> marca é referenciado 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 de desenvolvedor, o withDisambiguation método converte automaticamente o valor fornecido em minúsculas e emite um aviso no console do desenvolvedor se o valor fornecido contiver caracteres não minúsculas. Esse método auxiliar não higieniza completamente a entrada e a chamada de 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 Estrutura do SharePoint com React

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

O exemplo a seguir mostra uma Web Part mínima que mostra como usar o Microsoft Graph Toolkit com disambiguation em web parts Estrutura do SharePoint baseadas em React. Para obter exemplos mais completos, consulte o exemplo React Web Part do 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 Web Part de nível superior importar qualquer código de @microsoft/mgt-react ou @microsoft/mgt-components, a desambiguação não terá efeito.

Em seguida, os componentes subjacentes podem usar componentes do kit de ferramentas do @microsoft/mgt-react pacote, como de costume. Devido às etapas de configuração anteriores, o kit de ferramentas React componentes renderizará HTML usando os nomes de marca 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 em React

Para usar a disambiguação em um aplicativo React, chame customElementHelper.withDisambiguation() antes de carregar e renderizar seu componente raiz. Para ajudar com o carregamento lento nesse cenário, React fornece a função e Suspense o lazy componente em React versão 16.6 e para cima.

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

Para usar o recurso de disambiguação ao usar HTML padrão e JavaScript, 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>

Importante

O import de mgt-components deve usar uma importação dinâmica para garantir que a disambiguação seja aplicada antes que os componentes sejam importados. Se uma importação estática for usada, ela será içada e a importação ocorrerá antes que a disambiguação possa ser aplicada.

Importações dinâmicas (carregamento lento)

Usando importações dinâmicas, você pode carregar dependências de forma assíncrona. Esse padrão permite carregar 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 carga inicial do seu aplicativo. No contexto de 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 disambiguação não será aplicada e o uso do nome da marca desambiguado não funcionará.

Ao usar 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 usar importações dinâmicas, você deve usar a import() função. A import() função retorna uma promessa que se resolve para o módulo. Você também pode usar o método para executar o then código depois que o módulo for carregado e o catch método para manipular quaisquer erros, 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>';

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

Compartilhar via