Microsoft Graph ツールキットのテンプレートTemplates in the Microsoft Graph Toolkit

コンポーネントのコンテンツを変更するには、カスタムテンプレートを使用します。Use custom templates to modify the content of a component.

すべての web コンポーネントは、要素に基づくテンプレートをサポート <template> しています。All web components support templates based on the <template> element. たとえば、コンポーネントのテンプレートを上書きするには、コンポーネント内に要素を追加し <template> ます。For example, to override the template of a component, add a <template> element inside a component.

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

データ型Data-type

各コンポーネントは、テンプレートとして使用できる複数のパーツを持つことができます。Each component can have multiple parts that can be templated. たとえば、 mgt-agenda コンポーネントでは、個別のイベント、個々のセクションヘッダー、読み込みビュー、データビューなし、その他のテンプレートをテンプレートとして使用できます。For example, in the mgt-agenda component, you can template individual events, individual section headers, loading view, no data view, and more. テンプレートを指定するには、 data-type テンプレートの属性を使用します。To indicate the template, use the data-type attribute on a template. たとえば、で各イベントをテンプレートするには、次のように mgt-agenda データ型を使用し event ます。For example, to template each event in the mgt-agenda, use the event data-type, as shown.

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

が指定されていない場合は data-type 、コンポーネント全体がテンプレートに置き換えられます。If no data-type is specified, the entire component will be replaced with the template. 同じ目的に使用することもでき data-type="default" ます。You can also use data-type="default" for the same purpose.

データのバインドBinding data

多くのテンプレートでは、データコンテキストとしてテンプレートに渡されるデータのバインドが許可されています。Many templates allow binding of data that is passed to the template as data context. たとえば、 event コンポーネント内のテンプレートは、 mgt-agenda {event} テンプレートで直接使用できるオブジェクトを渡します。For example, the event template in the mgt-agenda component passes an {event} object that can be used directly in the template. などの式を展開するには、二重中かっこを event.subject 使用します。To expand an expression, such as event.subject, use the double curly brackets.

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

この形式は、次の属性内でも使用できます。This format can also be used inside attributes:

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

注: また、などのオブジェクトを展開して {{event}} 、JSON 文字列として表示することもできます。Note: You can also expand objects such as {{event}} and they will render as JSON strings. これは、テンプレートを開発しているときに便利です。This can be useful when you're developing the templates.

バインド構文を変更するChange binding syntax

既定では、式を展開するには、二重中かっこ () を使用し {{expression}} ます。By default, to expand an expression, you use double curly brackets ( {{expression}} ). ただし、二重中かっこの構文が既に使用されている環境では、この構文を変更できます。However, you can change this syntax for environments where the double curly bracket syntax is already used. たとえば、次の使用例では、2角かっこ () を使用し [[expression]] ます。For example, the following example uses double square brackets ( [[expression]] ).

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

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

データコンテキストヘルパープロパティData context helper properties

テンプレートのデータコンテキストオブジェクトでは、次のプロパティを使用することもできます。The following properties can also be used with the data context object in your templates.

プロパティProperty 説明Description
$index$index ループ処理中に表示されるアイテムの数値インデックス data-forNumerical index of item being rendered while being looped with data-for.
$parent$parent テンプレートが別のテンプレート内でレンダリングされている場合、このプロパティを使用すると親データコンテキストにアクセスできます。If a template is rendered inside another template, this property allows you to access the parent data context.

次の例は、データ for ループでこのプロパティを使用する方法を示して $index います。The following example shows how to use the $index property in a data-for loop.

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

条件付きレンダリングConditional rendering

データコンテキストに基づいて、条件が true または false の場合にのみ要素をレンダリングすることができます。You might only want to render elements when a condition is true or false based on the data context. data-if属性と data-else 属性は、式を評価し、true または false の場合にのみ表示させることができます。The data-if and data-else attributes can evaluate an expression and render only if true or 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>

ループLooping

データコンテキストオブジェクトにループが含まれている場合は、データをループする必要があります。There will be cases where the data context object contains loop and you will need to loop over the data. このシナリオでは、属性を使用し data-for ます。For this scenario, use the data-for attribute.

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

テンプレートのコンテキストTemplate context

バインド内のデータを変換する必要がある場合、イベントにバインドする場合、またはテンプレートバインドで外部データを使用する場合は、テンプレートで外部データコンテキストへのバインドがサポートされています。In scenarios where you need to convert data in your bindings, bind to events, or just use external data in your templates bindings, the templates support binding to external data context. その他のテンプレートコンテキストを追加するには、次の2つの方法があります。You can add additional template context in two ways:

  1. コンポーネント上で直接。Directly on the component.

    各コンポーネントは templateContext プロパティを定義します。これを使用すると、コンポーネント内の任意のテンプレートに追加のデータを渡すことができます。Each component defines the templateContext property, which you can use to pass additional data to any template in the component.

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

    オブジェクト内のプロパティは、 templateContext テンプレートのバインド式で使用できるようになります。The properties in the templateContext object will now be available to be used in the binding expressions in the template.

  2. すべてのコンポーネントに対してグローバルに行います。Globally for all components.

    クラスは、オブジェクトを公開して、 TemplateHelper globalContext すべてのコンポーネントでグローバルに使用できるようにするデータまたは関数を追加します。The TemplateHelper class exposes the globalContext object to add data or functions that should be globally available for all components.

    import { TemplateHelper } from '@microsoft/mgt';
    
    TemplateHelper.globalContext.someObject = {};
    TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
    TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }
    

文書Converters

多くの場合、データをテンプレートに表示する前に変換する必要があります。In many cases, you might want to transform the data before presenting it in the template. たとえば、表示する前に日付の書式を正しく設定することができます。For example, you might want to properly format a date before it is rendered. このような場合は、テンプレートコンバータを使用することをお勧めします。In these cases, you might want to use a template converter.

テンプレートコンバータを使用するには、まず、変換を行う関数を定義する必要があります。To use a template converter, you first need to define a function that will do the conversion. たとえば、関数を定義して、イベントオブジェクトを書式設定された時間範囲に変換することができます。For example, you might define a function to convert an event object to a formatted time range.

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

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

    return timeRange;
  }

}

テンプレートでコンバータを使用するには、分離コードで関数を使用する場合と同じように使用します。To use the converter in your template, use it as if you would use a function in code behind.

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

イベントまたはプロパティのバインドEvent or property binding

この属性を使用すると、 data-props イベントリスナーを追加したり、テンプレートにプロパティ値を直接設定したりできます。The data-props attribute allows you to add an event listener or set a property value directly in your templates.

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

データを指定するには、設定するプロパティやイベントハンドラーごとにコンマ区切りの文字列を指定します。The data-props accepts a comma delimited string for each property or event handler you might want to set.

イベントハンドラーを追加するには、イベントの名前の前にを付け @ ます。To add an event handler, prefix the name of the event with @. イベントハンドラーは、要素ので使用できる必要があり templateContext ます。The event handler will need to be available in the templateContext of the element.

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

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

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

イベント args、データコンテキスト、およびテンプレートのルート要素は、パラメーターとしてイベントハンドラーに渡されます。The event args, data context, and the root element of the template are passed to the event handler as parameters.

テンプレートでレンダリングされたイベントTemplate rendered event

場合によっては、レンダリングされた要素への参照を取得する必要があります。In certain cases, you might want to get a reference to the rendered element. これは、コンテンツのレンダリングを自分で処理したり、レンダリングされた要素を変更したりする場合に役立ちます。This can be useful if you want to handle the rendering of the content yourself, or you want to modify the rendered element.

このシナリオでは、 templateRendered テンプレートがレンダリングされた後に発生するイベントを使用できます。In this scenario, you can use the templateRendered event, which fires after the template has been rendered.

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

イベントの詳細には、レンダリングされている要素への参照、データコンテキストオブジェクト、およびテンプレートの種類が含まれます。The event details will contain a reference to the element that is being rendered, the data context object, and the type of the template.

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', () => {});
  }
});

スタイルStyling

テンプレートは、シャドウ dom の外側でレンダリングされるときに、通常 CSS を使用してスタイル設定できます。The templates can be styled normally via CSS as they are rendered outside of the shadow dom.