Microsoft Graph 工具包中的模板

  • 项目

大多数 Microsoft Graph 工具包组件都支持使用自定义模板来修改组件的内容。

所有 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 工具包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>

注意：还可以展开 或 等{{event}}{{this}}对象，它们将呈现为 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 。 最简单的形式是添加 {{this}} 模板中的任意位置。

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

由于可以在绑定表达式中使用 JavaScript，因此还可以访问 对象， console 该对象允许在模板中使用 console.log(this) (或任何其他 console API) 。

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

条件呈现

你可能只想在基于数据上下文的条件为 true 或 false 时呈现元素。 data-if和 data-else 属性可以计算表达式，并且仅当为 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>

模板上下文

在需要转换绑定中的数据、绑定到事件或仅在模板绑定中使用外部数据的情况下，模板支持绑定到外部数据上下文。 可以通过两种方式添加其他模板上下文：

  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>

数据属性接受可能要设置的每个属性或事件处理程序的逗号分隔字符串。

若要添加事件处理程序，请在事件名称前面加上 @。 事件处理程序需要在 元素的 中 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', () => {});
  }
});

造型

模板通常可以通过 CSS 设置样式，因为它们呈现在阴影 dom 之外。