Microsoft Graph Toolkit のテンプレート

[アーティクル]
11/07/2024

ほとんどの Microsoft Graph Toolkit コンポーネントでは、カスタムテンプレートを使用してコンポーネントのコンテンツを変更できます。

すべての Web コンポーネントは、要素に基づくテンプレートを <template> サポートします。たとえば、コンポーネントのテンプレートをオーバーライドするには、コンポーネント内に <template> 要素を追加します。

<mgt-agenda>
  <template data-type="event">
      <div>{{event.subject}}</div>
      <div data-for='attendee in event.attendees'>
          <mgt-person person-query="{{attendee.emailAddress.name}}">
            <template>
              <div data-if="person.image">
                <img src="{{person.image}}" />
              </div>
              <div data-else>
                {{person.displayName}}
              </div>
            </template>
          </mgt-person>
      </div>
  </template>
</mgt-agenda>

Microsoft Graph Toolkit React コンポーネントを使用している場合は、テンプレートの作成にReactを使用できます。詳細については、「Reactでツールキットを使用する」を参照してください。

データ型

各コンポーネントには、テンプレート化できる複数のパーツを含めることができます。たとえば、コンポーネントでは、個々の mgt-agenda イベント、個々のセクションヘッダー、読み込みビュー、データビューなしなどをテンプレート化できます。テンプレートを示すには、テンプレートの data-type 属性を使用します。たとえば、で各イベントを mgt-agendaテンプレートするには、次に示すように、データ型を event 使用します。

<mgt-agenda>
  <template data-type="event"> </template>
</mgt-agenda>

が指定されていない data-type 場合、コンポーネント全体がテンプレートに置き換えられます。同じ目的で使用 data-type="default" することもできます。

データのバインド

多くのテンプレートでは、データコンテキストとしてテンプレートに渡されるデータのバインドが許可されています。たとえば、コンポーネント内の event テンプレートは mgt-agenda 、テンプレートで直接使用できるオブジェクトを渡 {event} します。などの event.subject式を展開するには、二重中かっこを使用します。

<template data-type="event">
  <div>{{event.subject}}</div>
</template>

この形式は、属性内でも使用できます。

<template data-type="event">
  <a href="{{ event.onlineMeetingUrl }}" />
</template>

メモ：や {{this}} などの{{event}}オブジェクトを展開して、JSON 文字列としてレンダリングすることもできます。これは、テンプレートを開発する場合に役立ちます。

バインド構文の変更

既定では、式を展開するには、二重中かっこ ( {{expression}} ) を使用します。ただし、二重中かっこ構文が既に使用されている環境では、この構文を変更できます。たとえば、次の例では、二重角かっこ ( [[expression]] ) を使用します。

import { TemplateHelper } from '@microsoft/mgt';

TemplateHelper.setBindingSyntax('[[', ']]');

データコンテキストヘルパーのプロパティ

次のプロパティは、テンプレート内のデータコンテキストオブジェクトでも使用できます。

プロパティ	説明
$index	で `data-for`ループ中にレンダリングされる項目の数値インデックス。
$parent	テンプレートが別のテンプレート内にレンダリングされる場合、このプロパティを使用すると、親データコンテキストにアクセスできます。

次の例は、data-for ループでプロパティを $index 使用する方法を示しています。

<mgt-person>
  <mgt-person-card>
    <template data-type="additional-details">
      <span data-for="language in languages">
        {{ language.displayName }}<span data-if="$index < languages.length - 1">, </span>
      </span>
    </template>
  </mgt-person-card>
</mgt-person>

データコンテキストをデバッグするために、バインド式でを使用 this できます。最も簡単な形式は、テンプレート内の任意の場所に追加 {{this}} することです。

<template data-type="event">
  <div>
    {{this}}
  </div>
</template>

バインド式で JavaScript を使用できるため、テンプレートで (またはその他consoleの API) を使用console.log(this)できるオブジェクトにもアクセスconsoleできます。

<template data-type="event">
  <div>
    {{console.log(this)}}
  </div>
</template>

条件付きレンダリング

データコンテキストに基づいて条件が true または false の場合にのみ要素をレンダリングできます。属性と data-else 属性はdata-if、式を評価し、true または false の場合にのみレンダリングできます。

<mgt-person person-query="john doe">
  <template>
    <div data-if="person.image">
      <img src="{{ person.image }}" />
    </div>
    <div data-else>
      {{ person.displayName }}
    </div>
  </template>
</mgt-person>

ループ

データコンテキストオブジェクトにループが含まれており、データをループする必要がある場合があります。このシナリオでは、属性を使用します data-for 。

<template data-type="event">
  <ul>
    <li data-for='attendee in event.attendees'>
      {{ attendee.displayName }}
    </li>
  </ul>
</template>

テンプレートコンテキスト

バインド内のデータの変換、イベントへのバインド、またはテンプレートバインドで外部データのみを使用する必要があるシナリオでは、テンプレートは外部データコンテキストへのバインドをサポートします。テンプレートコンテキストは、次の 2 つの方法で追加できます。

コンポーネント上で直接。

各コンポーネントはプロパティを templateContext 定義します。このプロパティを使用すると、コンポーネント内の任意のテンプレートに追加のデータを渡すことができます。
```
document.querySelector('mgt-agenda').templateContext = {

  someObject: {},
  formatDate: (date: Date) => { /* format date and return */ },
  someEventHandler: (e) => { /* handleEvent */  }

}
```
オブジェクトの templateContext プロパティをテンプレートのバインド式で使用できるようになりました。

すべてのコンポーネントに対してグローバルに。

クラスは TemplateHelper 、オブジェクトを globalContext 公開して、すべてのコンポーネントでグローバルに使用できるデータまたは関数を追加します。

import { TemplateHelper } from '@microsoft/mgt';

TemplateHelper.globalContext.someObject = {};
TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }

コンバーター

多くの場合、テンプレートでデータを表示する前にデータを変換することが必要になる場合があります。たとえば、表示する前に日付を適切に書式設定することができます。このような場合は、テンプレートコンバーターを使用できます。

テンプレートコンバーターを使用するには、最初に変換を実行する関数を定義する必要があります。たとえば、イベントオブジェクトを書式設定された時間範囲に変換する関数を定義できます。

document.querySelector('mgt-agenda').templateContext = {

  getTimeRange: (event) => {
    // TODO: format a string from the event object as you wish
    // timeRange = ...

    return timeRange;
  }

}

テンプレートでコンバーターを使用するには、コードビハインドで関数を使用するかのように使用します。

<template data-type="event">
  <div>{{ getTimeRange(event) }}</div>
</template>

イベントまたはプロパティのバインド

属性 data-props を使用すると、イベントリスナーを追加したり、テンプレートに直接プロパティ値を設定したりできます。

<template>
    <button data-props="{{@click: myEvent, myProp: value}}"></button>
</template>

data-props は、設定するプロパティまたはイベントハンドラーごとにコンマ区切り文字列を受け取ります。

イベントハンドラーを追加するには、イベントの名前の前にを付 @けます。イベントハンドラーは、要素ので templateContext 使用できる必要があります。

document.querySelector('mgt-agenda').templateContext = {

  someEventHandler: (e, context, root) => { /* handleEvent */  }

}

<template>
    <button data-props="{{@click: someEventHandler}}"></button>
</template>

テンプレートのイベント引数、データコンテキスト、ルート要素は、パラメーターとしてイベントハンドラーに渡されます。

テンプレートレンダリングイベント

場合によっては、レンダリングされた要素への参照を取得することもできます。これは、コンテンツのレンダリングを自分で処理する場合や、レンダリングされた要素を変更する場合に便利です。

このシナリオでは、テンプレートのレンダリング後に templateRendered 発生するイベントを使用できます。

let agenda = document.querySelector('mgt-agenda');
agenda.addEventListener('templateRendered', (e) => { });

イベントの詳細には、レンダリングされる要素、データコンテキストオブジェクト、およびテンプレートの型への参照が含まれます。

agenda.addEventListener('templateRendered', (e) => {
  let templateType = e.detail.templateType;
  let dataContext = e.detail.context;
  let element = e.detail.element;

  if (templateType === 'event') {
    element.querySelector('.some-button').addEventListener('click', () => {});
  }
});

スタイリング

テンプレートは、シャドウ dom の外側にレンダリングされるため、CSS を使用して通常のスタイルを設定できます。

次の方法で共有

Microsoft Graph Toolkit のテンプレート

データ型

データのバインド

バインド構文の変更

データコンテキストヘルパーのプロパティ

{{this}}

条件付きレンダリング

ループ

テンプレートコンテキスト

コンバーター

イベントまたはプロパティのバインド

テンプレートレンダリングイベント

スタイリング

フィードバック

その他のリソース

次の方法で共有

Microsoft Graph Toolkit のテンプレート

データ型

データのバインド

バインド構文の変更

データ コンテキスト ヘルパーのプロパティ

{{this}}

条件付きレンダリング

ループ

テンプレート コンテキスト

コンバーター

イベントまたはプロパティのバインド

テンプレートレンダリングイベント

スタイリング

フィードバック

その他のリソース

データコンテキストヘルパーのプロパティ

テンプレートコンテキスト