Microsoft Graph Toolkit のテンプレート

ほとんどの 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('[[', ']]');

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

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

次の例は、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 できます。 最も簡単な形式は、テンプレート内の任意の場所に追加 {{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 つの方法で追加できます。

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

   各コンポーネントは プロパティを templateContext 定義します。このプロパティを使用すると、コンポーネント内の任意のテンプレートに追加のデータを渡すことができます。

   document.querySelector('mgt-agenda').templateContext = {
   
     someObject: {},
     formatDate: (date: Date) => { /* format date and return */ },
     someEventHandler: (e) => { /* handleEvent */  }
   
   }
   

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

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

   クラスは 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 を使用して通常のスタイルを設定できます。