Шаблоны в наборе средств Microsoft Graph

Статья
03/26/2023

Большинство компонентов Microsoft Graph Toolkit поддерживают использование пользовательских шаблонов для изменения содержимого компонента.

Все веб-компоненты поддерживают шаблоны на <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>

Примечание: Вы также можете развернуть такие объекты, как {{event}} или , {{this}} и они будут отображаться в виде строк JSON. Это может быть полезно при разработке шаблонов.

Изменение синтаксиса привязки

По умолчанию для развертывания выражения используются двойные фигурные скобки ( {{expression}} ). Однако этот синтаксис можно изменить для сред, в которых уже используется синтаксис двойной фигурной скобки. Например, в следующем примере используются двойные квадратные скобки ( [[expression]] ).

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

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

Вспомогательные свойства контекста данных

Следующие свойства также можно использовать с объектом контекста данных в шаблонах.

Свойство	Описание
$index	Числовой индекс элемента, отрисовываемого при цикле с `data-for`помощью .
$parent	Если шаблон отображается внутри другого шаблона, это свойство позволяет получить доступ к родительскому контексту данных.

В следующем примере показано, как использовать $index свойство в цикле data-for.

<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 , который позволяет использовать 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>

Контекст шаблона

В сценариях, когда необходимо преобразовать данные в привязках, привязать к событиям или просто использовать внешние данные в привязках шаблонов, шаблоны поддерживают привязку к контексту внешних данных. Добавить дополнительный контекст шаблона можно двумя способами:

Непосредственно на компоненте.

Каждый компонент определяет 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', () => {});
  }
});

Стиль

Шаблоны можно стильировать обычно с помощью CSS, так как они отрисовываются за пределами теневой модели.