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

注意

Microsoft Graph Toolkit は非推奨です。 2025 年 9 月 1 日から、2026 年 8 月 28 日に完全な退職が予定されています。 開発者は、Web エクスペリエンスを構築するために、Microsoft Graph SDK またはその他のサポートされている Microsoft Graph ツールを使用して移行する必要があります。 詳細については、 非推奨のお知らせを参照してください。

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 ヘルパー関数は、React.lazyとReact.Suspenseを使用してこれらのコンポーネントを最上位の Web パーツから遅延読み込みしやすくするために存在します。 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-react または @microsoft/mgt-componentsからコードをインポートした場合、あいまいさの解消は効果がありません。

基になるコンポーネントでは、 @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 以降のlazy関数とSuspense コンポーネントReact提供します。

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

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