Microsoft Graph Toolkit コンポーネントのあいまいさの解消

[アーティクル]
02/14/2024

Microsoft Graph Toolkit は、Web コンポーネントを使用して構築されています。 Web コンポーネントは、ブラウザー内で登録するときに、タグ名を一意のキーとして使用します。以前に登録したタグ名を使用してコンポーネントを登録しようとすると、を呼び出 CustomElementRegistry.define()すときにエラーが発生します。複数のカスタムアプリケーションを 1 つのページに読み込めるシナリオでは、Microsoft Graph Toolkit の問題が発生します。特に、SharePoint Frameworkを使用してソリューションを開発するときに問題が発生します。

パッケージは、 mgt-spfx この課題を軽減するのに役立ちます。を使用 mgt-spfxすると、テナントにデプロイされているすべての SPFx ソリューションに対して Microsoft Graph Toolkit Web コンポーネントの登録を一元化できます。ツールキットコンポーネントを中央の場所から再利用することで、エラーをスローすることなく、さまざまなソリューションの Web パーツを 1 つのページに読み込むことができます。を使用 mgt-spfxすると、SharePoint テナント内のすべての Microsoft Graph Toolkit ベースの Web パーツで、同じバージョンのツールキットが使用されます。

あいまいさの解消機能を使用すると、最新バージョンの Microsoft Graph Toolkit を使用して Web パーツを構築し、v2.x を使用する Web パーツと共にページに読み込むことができます。この機能を使用すると、アプリケーション内のすべてのツールキット Web コンポーネントのタグ名に追加する一意の文字列を指定できます。あいまいさを解消する場合、指定された値はタグ名の 2 番目のセグメントとして挿入されるため、タグを使用 customElementHelper.withDisambiguation('foo') する場合はを <mgt-login> 使用して <mgt-foo-login>参照されます。

を呼び出して CustomElementRegistry.define()カスタム要素を登録する場合、入力される名前は有効なカスタム要素名である必要があります。開発者エクスペリエンスを向上させるために、メソッドは withDisambiguation 指定された値を自動的に小文字に変換し、指定された値に小文字以外の文字が含まれている場合は、開発者コンソールで警告を発行します。このヘルパーメソッドは入力を完全にサニタイズしません。基になる define メソッド呼び出しは、のような DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mgt-MyName-flyout" is not a valid custom element nameエラーで失敗する可能性があります。

Reactを使用した web パーツSharePoint Framework使用

Reactを使用して web パーツSharePoint Framework構築する場合、ライブラリから@microsoft/mgt-reactインポートするすべてのコンポーネントは、あいまいさを解消する設定を構成した後で非同期的に読み込む必要があります。ヘルパー関数はlazyLoadComponent、最上位の Web パーツからのこれらのコンポーネントの遅延読み込みを容易にするためにReact.lazyReact.Suspense存在します。関数は lazyLoadComponent パッケージで @microsft/mgt-spfx-utils 提供されます。あいまいさの解消値は Web コンポーネントのレンダリング時にのみ使用されるため、コード内で特定のコンポーネントを参照する方法に変更Reactはありません。

次の例は、Microsoft Graph Toolkit を使用して、React ベースのSharePoint Framework Web パーツであいまいさを解消する方法を示す最小限の Web パーツを示しています。より完全な例については、「React SharePoint Web パーツサンプル」を参照してください。

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

メモ：最上位の Web パーツがまたは @microsoft/mgt-componentsから@microsoft/mgt-reactコードをインポートする場合、あいまいさの解消は効果がありません。

基になるコンポーネントは、通常どおりパッケージのツールキットコンポーネントを @microsoft/mgt-react 使用できます。以前のセットアップ手順により、ツールキット React コンポーネントは、明確なタグ名を使用して HTML をレンダリングします。

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

Reactでの使用状況

React アプリケーションであいまいさを利用するには、ルートコンポーネントを読み込んでレンダリングする前にを呼び出customElementHelper.withDisambiguation()します。このシナリオでの遅延読み込みを支援するために、Reactはバージョン 16.6 以降で関数とSuspenseコンポーネントReact提供lazyします。

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

標準 HTML と JavaScript での使用法

標準 HTML と JavaScript を使用するときにあいまいさを解消する機能を使用するには、モジュールをインポートする前にを@microsoft/mgt-components呼び出customElementHelper.withDisambiguation()します。

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

重要

のmgt-componentsではimport、コンポーネントをインポートする前に、動的インポートを使用してあいまいさが適用されるようにする必要があります。静的インポートを使用すると、そのインポートはホイストされ、あいまいさを解消する前にインポートが行われます。

動的インポート (遅延読み込み)

動的インポートを使用すると、依存関係を非同期的に読み込むことができます。このパターンを使用すると、必要な場合にのみ依存関係を読み込むことができます。たとえば、ユーザーがボタンをクリックしたときにのみコンポーネントを読み込むことができます。これは、アプリケーションの初期読み込み時間を短縮するための優れた方法です。あいまいさのコンテキストでは、コンポーネントがインポートされるときにブラウザーに自身が登録されるため、この手法を使用する必要があります。

大事な： あいまいさを適用する前にコンポーネントをインポートした場合、あいまいさの解消は適用されず、あいまいでないタグ名を使用しても機能しません。

ステートメントを使用すると import 、import ステートメントがホイストされ、コードブロック内の他のコードの前に実行されます。動的インポートを使用するには、関数を使用する import() 必要があります。関数は import() 、モジュールに解決される promise を返します。また、メソッドを then 使用して、モジュールが読み込まれた後にコードを実行し、 catch 必要に応じてメソッドを使用してエラーを処理することもできます。

動的インポートの使用例

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

静的インポートの使用例

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

メモ： 静的インポートではあいまいさを解消できません。